145 lines
5.1 KiB
Markdown
145 lines
5.1 KiB
Markdown
# Project Optima — UI
|
|
|
|
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).
|
|
|
|
Built with **SvelteKit**, **TypeScript**, **Tailwind CSS**, and **Electron**.
|
|
|
|
## Features
|
|
|
|
- **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
|
|
|
|
## Tech Stack
|
|
|
|
| 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
|
|
|
|
### Prerequisites
|
|
|
|
- [Bun](https://bun.sh/) (package manager & runtime)
|
|
- [Node.js 22+](https://nodejs.org/) (for Electron)
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
bun install
|
|
```
|
|
|
|
> **Note:** This project patches `@sveltejs/kit` via `patches/` to work around routing issues.
|
|
|
|
### Development (Desktop)
|
|
|
|
```bash
|
|
bun start
|
|
```
|
|
|
|
Launches Electron with Vite HMR. The app opens to the login page and connects to the Optima API.
|
|
|
|
### Development (Web Server)
|
|
|
|
```bash
|
|
bun run build:server
|
|
node build/index.js
|
|
```
|
|
|
|
Builds and runs the SvelteKit server with `adapter-node` on port 3000.
|
|
|
|
## Building
|
|
|
|
### Desktop — macOS
|
|
|
|
```bash
|
|
bun run make:macos
|
|
```
|
|
|
|
Outputs `.dmg` and `.zip` to `out/make/`.
|
|
|
|
### Desktop — Windows
|
|
|
|
```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.
|