191 lines
6.9 KiB
Markdown
191 lines
6.9 KiB
Markdown
# Vela Platform v2
|
||
|
||
Single FastAPI application that powers the Vela business — a home server installation service in Casablanca, Morocco.
|
||
|
||
**Built:** June 26, 2026
|
||
**Deployed:** Proxmox CT 124 @ 192.168.1.244
|
||
|
||
---
|
||
|
||
## Architecture
|
||
|
||
```
|
||
┌─────────────────────────────────────────┐
|
||
│ nginx :80 │
|
||
│ ├── / → Marketing site │
|
||
│ ├── /admin → Admin P&L dashboard │
|
||
│ ├── /backup → Backup explainer │
|
||
│ ├── /static/* → Logos, assets │
|
||
│ └── /api/* → JSON API │
|
||
│ │ │
|
||
│ uvicorn :8000 (systemd: vela.service) │
|
||
│ ├── main.py — FastAPI app │
|
||
│ ├── models.py — SQLAlchemy models │
|
||
│ ├── database.py — SQLite WAL mode │
|
||
│ └── auth.py — JWT auth │
|
||
│ │
|
||
│ vela.db (SQLite) │
|
||
└─────────────────────────────────────────┘
|
||
```
|
||
|
||
One box. One app. One database. No microservices.
|
||
|
||
---
|
||
|
||
## What It Does
|
||
|
||
### Public Marketing Site (`/`)
|
||
- Bilingual FR/EN with URL-based language toggle (`?lang=fr` / `?lang=en`)
|
||
- Dark/light mode toggle (persisted in localStorage)
|
||
- Hero section with value proposition
|
||
- Problem/solution section
|
||
- Live pricing cards pulled from API
|
||
- Immich & Nextcloud sections with real SVG logos
|
||
- "How it works" — 3-step visual
|
||
- WhatsApp CTA buttons (all pointing to +212 725-569519)
|
||
- Footer with barely-visible "Admin" link (30% opacity)
|
||
|
||
### Backup Explainer (`/backup`)
|
||
- Explains backups to non-technical users
|
||
- Simple vs redundant backup comparison
|
||
- "The golden rule: if it only exists in one place, it doesn't really exist"
|
||
- Bilingual
|
||
|
||
### Admin Panel (`/admin`)
|
||
- JWT login (username: `oimwiodev`, password: `kxdr781020`)
|
||
- Token stored in localStorage, verified via `/api/verify`
|
||
- 4 tabs: Dashboard, Tiers, Transactions, Expenses
|
||
|
||
#### Dashboard
|
||
- Real-time P&L cards: Revenue, COGS, Gross Profit, Margin %, Expenses, Net Profit
|
||
- Monthly breakdown table with month filter
|
||
- Formula: **Revenue − COGS − Expenses = Net Profit** (not the fake v1 math)
|
||
|
||
#### Tiers
|
||
- 4 tiers: Rif, Rif+, Atlas, Atlas+
|
||
- Component breakdown with unit costs
|
||
- Inline edit: tier name, sell price, component costs
|
||
- Toggle active/inactive
|
||
- Cost price auto-calculated from components
|
||
- Margin % shown per tier
|
||
|
||
#### Transactions
|
||
- Add manual sale (select tier → snapshots sell price + cost at time of sale)
|
||
- Filter by month
|
||
- Delete with confirm + undo timer:
|
||
- 1st click: "Sure?" (4s timeout)
|
||
- 2nd click: deletes, row fades, 8s undo window
|
||
|
||
#### Expenses
|
||
- Add/delete expenses with month and category
|
||
- Monthly expense templates (auto-generate from templates)
|
||
- Soft delete (deleted_at timestamp)
|
||
|
||
---
|
||
|
||
## API Endpoints
|
||
|
||
### Public (no auth)
|
||
| Method | Path | Description |
|
||
|--------|------|-------------|
|
||
| GET | `/api/public/pricing` | Active tiers: name, description, sell_price |
|
||
| GET | `/api/public/services/{id}` | Single tier details + components |
|
||
|
||
### Auth
|
||
| Method | Path | Description |
|
||
|--------|------|-------------|
|
||
| POST | `/api/auth/login` | Login (username + password) → JWT |
|
||
| POST | `/api/auth/logout` | Clear cookie |
|
||
| GET | `/api/verify` | Verify JWT, returns email |
|
||
|
||
### Admin (JWT required)
|
||
| Method | Path | Description |
|
||
|--------|------|-------------|
|
||
| GET | `/api/pnl` | P&L summary + monthly breakdown |
|
||
| GET | `/api/services` | All tiers with components |
|
||
| PUT | `/api/services/{id}` | Update tier (name, price, active, etc.) |
|
||
| PUT | `/api/services/{id}/toggle` | Toggle active/inactive |
|
||
| PUT | `/api/services/{id}/components/{cid}` | Update component cost/qty |
|
||
| GET | `/api/transactions` | List transactions (optional `?month=`) |
|
||
| POST | `/api/transactions` | Create sale (snapshots prices) |
|
||
| DELETE | `/api/transactions/{id}` | Delete transaction |
|
||
| GET | `/api/expenses` | List expenses |
|
||
| POST | `/api/expenses` | Add expense |
|
||
| DELETE | `/api/expenses/{id}` | Soft-delete expense |
|
||
| GET | `/api/expense-templates` | List recurring templates |
|
||
| POST | `/api/expenses/generate-month` | Generate from templates |
|
||
|
||
---
|
||
|
||
## Database Schema
|
||
|
||
6 tables in SQLite (`vela.db`):
|
||
|
||
| Table | Purpose |
|
||
|-------|---------|
|
||
| `users` | Single admin (email, bcrypt password) |
|
||
| `services` | 4 tiers (name, sell_price, cost_price, active, sort_order) |
|
||
| `service_components` | Per-tier parts (name, unit_cost, quantity) |
|
||
| `transactions` | Frozen sales with price/cost snapshots, unique (source_type, source_id) |
|
||
| `expenses` | Monthly costs with soft delete |
|
||
| `expense_templates` | Recurring expense patterns |
|
||
|
||
Key design: **transactions freeze sell_price and cost_price at time of sale.** If you change an SSD cost later, old sales don't change. Real P&L math.
|
||
|
||
SQLite pragmas: `journal_mode=WAL`, `foreign_keys=ON`, `busy_timeout=5000`
|
||
|
||
---
|
||
|
||
## Deployment
|
||
|
||
**Server:** Proxmox CT 124 (Debian 12)
|
||
**IP:** 192.168.1.244
|
||
**Service:** `systemctl restart vela`
|
||
**Files:** `/opt/vela/`
|
||
**DB:** `/opt/vela/vela.db`
|
||
|
||
### Update workflow
|
||
```bash
|
||
# 1. Edit files locally
|
||
# 2. Package and deploy
|
||
cd ~/src/vela-platform
|
||
tar czf /tmp/vela-update.tar.gz main.py templates/
|
||
sshpass -p 'PW' scp /tmp/vela-update.tar.gz root@192.168.1.109:/tmp/
|
||
sshpass -p 'PW' ssh root@192.168.1.109 "
|
||
pct push 124 /tmp/vela-update.tar.gz /tmp/vela-update.tar.gz &&
|
||
pct exec 124 -- bash -c 'cd /opt/vela && tar xzf /tmp/vela-update.tar.gz && systemctl restart vela'
|
||
"
|
||
```
|
||
|
||
### Public access
|
||
Point Nginx Proxy Manager at `192.168.1.244:80` for your domain.
|
||
|
||
---
|
||
|
||
## Design Decisions
|
||
|
||
- **No Jinja2** — hit a cache bug (`unhashable type: 'dict'`). Switched to `FileResponse` serving raw HTML. All dynamic content via `fetch()` to JSON APIs.
|
||
- **No framework** — vanilla HTML/CSS/JS. No React, no Vue, no build step.
|
||
- **CSS variables** — dark/light mode is a single `data-theme` attribute. Zero hardcoded hex colors in JS.
|
||
- **Single admin** — no user management. One account. Simple.
|
||
- **Public API is read-only** — pricing only. No costs, no margins, no internals leak.
|
||
|
||
---
|
||
|
||
## WhatsApp Sales Bot
|
||
|
||
A separate Hermes agent with a custom SOUL.md handles WhatsApp conversations. The bot:
|
||
- Answers questions in French/Darija/English
|
||
- Fetches live pricing via `curl http://192.168.1.244/api/public/pricing`
|
||
- Follows a 4-step sales process: understand → recommend → handle objections → close
|
||
- Never hardcodes prices — always checks the API
|
||
- Personality: calm, direct, short messages, no corporate tone
|
||
|
||
SOUL.md at `/tmp/vela-sales-bot-soul.md`
|
||
|
||
---
|
||
|
||
## What Was Removed (v1)
|
||
|
||
The old Vela had **two separate LXCs** (CT125 + CT126) with **three Python services** (two FastAPI apps + nginx, two auth systems, two databases). All nuked. Replaced with this single monolith.
|