feat: add procurement and sales sections
This commit is contained in:
@@ -1,116 +1,144 @@
|
||||
# SveltronKit
|
||||
# Project Optima — UI
|
||||
|
||||
A minimal template for building Electron apps with SvelteKit.
|
||||
The frontend for **Project Optima**, a credential and company management platform. Ships as both a **web application** (deployed to Kubernetes) and a **cross-platform desktop app** (Electron for macOS and Windows).
|
||||
|
||||
Includes native support for Typscript and uses Electron's official recommended Electron Forge for packaging.
|
||||
Built with **SvelteKit**, **TypeScript**, **Tailwind CSS**, and **Electron**.
|
||||
|
||||
Everything you can do in SvelteKit, you can do in SveltronKit; meaning that you can use component
|
||||
libraries like [Shadcn-Svelte](https://next.shadcn-svelte.com/).
|
||||
## Features
|
||||
|
||||
> [!IMPORTANT]
|
||||
> This template uses SvelteKit's [hash router](https://svelte.dev/docs/kit/configuration#router) to
|
||||
> create a single-page app. The only difference you'll have to look out for is to start all your routed
|
||||
> links with `#/` instead of `/`.
|
||||
- **Authentication** — OAuth-based login flow via the Optima API
|
||||
- **Company Management** — Browse and manage companies and linked Unifi sites
|
||||
- **Credential Management** — Create, view, and organize credentials by type
|
||||
- **Admin Panel** — User management, role & permission assignment, credential type configuration
|
||||
- **Dark/Light Theme** — Toggle between themes with persistent preference
|
||||
- **Desktop App** — Native macOS (.dmg) and Windows (.exe/.msi) builds via Electron Forge
|
||||
- **Web Deployment** — Containerized SvelteKit server deployed to Kubernetes
|
||||
|
||||
## Dependencies & Frameworks
|
||||
## Tech Stack
|
||||
|
||||
- [SvelteKit](https://kit.svelte.dev/)
|
||||
- [Electron](https://www.electronjs.org/)
|
||||
- [Electron Forge](https://www.electronforge.io/)
|
||||
- [TypeScript](https://www.typescriptlang.org/)
|
||||
- [TailwindCSS](https://tailwindcss.com/)
|
||||
|
||||
> [!NOTE]
|
||||
> I've included TailwindCSS in this template because I use it in my own projects, but you can remove
|
||||
> it easily if you don't want it.
|
||||
| Layer | Technology |
|
||||
| --------------- | ----------------------------------------------------------------------------------------- |
|
||||
| Framework | [SvelteKit](https://kit.svelte.dev/) |
|
||||
| Language | [TypeScript](https://www.typescriptlang.org/) |
|
||||
| Styling | [Tailwind CSS v4](https://tailwindcss.com/) |
|
||||
| Desktop | [Electron](https://www.electronjs.org/) + [Electron Forge](https://www.electronforge.io/) |
|
||||
| API Client | [Axios](https://axios-http.com/) |
|
||||
| Realtime | [Socket.IO](https://socket.io/) |
|
||||
| Testing | [Vitest](https://vitest.dev/) + [Playwright](https://playwright.dev/) |
|
||||
| Package Manager | [Bun](https://bun.sh/) |
|
||||
|
||||
## Getting Started
|
||||
|
||||
> [!WARNING]
|
||||
> This project uses [`bun`](https://bun.sh/) and uses [patching](https://bun.sh/docs/install/patch) to work
|
||||
> around some issues with SvelteKit. When this [PR](https://github.com/sveltejs/kit/pull/13812) merges,
|
||||
> you can remove the patching and use the latest version of SvelteKit.
|
||||
### Prerequisites
|
||||
|
||||
Start by installing the dependencies:
|
||||
- [Bun](https://bun.sh/) (package manager & runtime)
|
||||
- [Node.js 22+](https://nodejs.org/) (for Electron)
|
||||
|
||||
```
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
bun install
|
||||
```
|
||||
|
||||
**Development:**
|
||||
> **Note:** This project patches `@sveltejs/kit` via `patches/` to work around routing issues.
|
||||
|
||||
```
|
||||
### Development (Desktop)
|
||||
|
||||
```bash
|
||||
bun start
|
||||
```
|
||||
|
||||
[Electron Forge](https://www.electronforge.io/) with the [Vite plugin](https://www.electronforge.io/plugins/vite)
|
||||
will take care of running the development server and building the app for you. You don't need to run
|
||||
`vite dev` or `vite build` yourself. This also means that it supports hot module replacement (HMR).
|
||||
Launches Electron with Vite HMR. The app opens to the login page and connects to the Optima API.
|
||||
|
||||
**Production:**
|
||||
### Development (Web Server)
|
||||
|
||||
```
|
||||
bun run package
|
||||
```bash
|
||||
bun run build:server
|
||||
node build/index.js
|
||||
```
|
||||
|
||||
This will build the app and you can find the output in the `out` directory. You can run the production
|
||||
app by opening the `.app` file in the `out` directory. This will not create your app's installer
|
||||
for distribution though.
|
||||
Builds and runs the SvelteKit server with `adapter-node` on port 3000.
|
||||
|
||||
To create a distributable installer, you can use:
|
||||
## Building
|
||||
|
||||
```
|
||||
bun run make
|
||||
### Desktop — macOS
|
||||
|
||||
```bash
|
||||
bun run make:macos
|
||||
```
|
||||
|
||||
This will create a distributable installer for your app. You can configure this in the `makers` section
|
||||
in `forge.config.ts`. Reference the [makers documentation](https://www.electronforge.io/makers) for more
|
||||
information.
|
||||
Outputs `.dmg` and `.zip` to `out/make/`.
|
||||
|
||||
# Electron Crash Course
|
||||
### Desktop — Windows
|
||||
|
||||
> [!NOTE]
|
||||
> This is a super simplified version of the Electron documentation meant to give you a general idea
|
||||
> of how Electron works and how each file corresponds to responsibilities in Electron. For a more
|
||||
> accurate description of how Electron works, you can refer to the [official documentation](https://www.electronjs.org/docs).
|
||||
|
||||
I found that most of the problems I encountered when setting up Electron were because I didn't know
|
||||
how Electron works and that the documentation was too dense to get up to speed with, so I'll include
|
||||
a crash course here. _I will be making a lot of analogies to web development_ as it seems like a lot
|
||||
of people who are new to Electron come from web development.
|
||||
|
||||
Because everything in Electron is client based, you'll need to host your own server if you want to
|
||||
access any sensitive logic like a database or authentication, etc.
|
||||
|
||||
## main.ts
|
||||
|
||||
This file defines what the main process will do. The process runs your app. It's the one that
|
||||
creates and manages windows and also has permissions to access the file system. You also define
|
||||
"_signals_"/"_endpoints_", through IPC, that let the renderer process (browser that runs your app)
|
||||
can "_call_" to interact with the file system.
|
||||
|
||||
By default, Electron will block off file system access to the renderer process as a security measure,
|
||||
which is the reason why you need to use IPC to interact with the file system.
|
||||
|
||||
## preload.ts
|
||||
|
||||
Think about this as a "bridge" or a "network"/"proxy" between the main process and the renderer process.
|
||||
You specify what functions that the renderer process can call and these functions will usually be
|
||||
interacting with the file system through the main process.
|
||||
|
||||
## renderer
|
||||
|
||||
The renderer process is the browser that runs your app. Just treat this like another SvelteKit app.
|
||||
|
||||
## Overview
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph main[Main Process]
|
||||
electron
|
||||
end
|
||||
subgraph renderer[Renderer Process]
|
||||
browser
|
||||
end
|
||||
electron <-- preload --> renderer
|
||||
```bash
|
||||
npm run make -- --platform win32
|
||||
```
|
||||
|
||||
Outputs `.exe`, `.msi`, and `.nupkg` to `out/make/`.
|
||||
|
||||
### Docker (Web Server)
|
||||
|
||||
```bash
|
||||
docker build -t optima-ui .
|
||||
docker run -p 3000:3000 optima-ui
|
||||
```
|
||||
|
||||
The Dockerfile builds the SvelteKit app, bundles it with `bun build` into a single file (no `node_modules` needed at runtime), and serves it on a minimal `node:22-alpine` image.
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
├── electron/ # Electron main & preload processes
|
||||
│ ├── main.ts # Window creation, IPC handlers
|
||||
│ └── preload.ts # Main ↔ Renderer bridge
|
||||
├── src/
|
||||
│ ├── components/ # Reusable Svelte components (modals, spinners, etc.)
|
||||
│ ├── lib/
|
||||
│ │ ├── optima-api/ # API client modules (auth, companies, credentials, etc.)
|
||||
│ │ ├── permissions.ts # Permission helpers
|
||||
│ │ └── theme.ts # Theme store (dark/light)
|
||||
│ ├── routes/
|
||||
│ │ ├── (auth)/ # Auth pages (login)
|
||||
│ │ ├── admin/ # Admin panel (users, roles, credential types)
|
||||
│ │ ├── companies/ # Company management
|
||||
│ │ └── +page.svelte # Home page
|
||||
│ └── styles/ # CSS (Tailwind)
|
||||
├── kubernetes/ # K8s deployment & ingress manifests
|
||||
├── .github/workflows/ # CI/CD (build, publish, deploy)
|
||||
├── Dockerfile # Multi-stage build (bun → node:alpine)
|
||||
└── forge.config.ts # Electron Forge config
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
# Unit tests (Vitest)
|
||||
bun run test:unit
|
||||
|
||||
# E2E tests (Playwright)
|
||||
bun run test:e2e
|
||||
|
||||
# All tests
|
||||
bun run test
|
||||
```
|
||||
|
||||
## Deployment
|
||||
|
||||
Releases are automated via GitHub Actions. Creating a release triggers:
|
||||
|
||||
1. **Docker image build** → pushed to `ghcr.io/project-optima/ttscm-ui`
|
||||
2. **Desktop builds** → macOS and Windows artifacts attached to the release
|
||||
3. **Kubernetes deploy** → rolls out the new image to the `optima` namespace
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description | Default |
|
||||
| ---------------- | -------------------------------- | --------------------------- |
|
||||
| `PUBLIC_API_URL` | Optima API base URL | `https://opt-api.osdci.net` |
|
||||
| `ORIGIN` | Allowed origin for CORS (server) | `https://optima.osdci.net` |
|
||||
| `PORT` | Server listen port | `3000` |
|
||||
|
||||
## License
|
||||
|
||||
See [LICENSE](LICENSE) for details.
|
||||
|
||||
Reference in New Issue
Block a user