📖 Add README with install guide, API docs, and overview

2026-06-15 23:12:00 +01:00
parent d1160673a7
commit d470966915
1 changed files with 130 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,130 @@
+# 🏔️ Vela Platform
+
+**Self-hosted P&L tracking for C2C server/storage businesses.**
+
+Track revenue, costs, and margins across multiple service offers with granular component-level pricing. No SaaS fees, no subscriptions — just Python + SQLite.
+
+---
+
+## 📸 Quick Overview
+
+| Page | What it does |
+|------|-------------|
+| **Dashboard** `/` | P&L cards (revenue/cost/margin), 12-month trend chart, active offers |
+| **Transactions** `/transactions` | Log monthly revenue per client, filter by month, auto-summary |
+| **Offers** `/services` | View/edit component pricing (HDD, RAM, CPU, Support, Transport...), auto-computed totals |
+
+## 🏔️ Offers
+
+| Offer | Description | Sell | Cost | Margin | Components |
+|-------|------------|------|------|--------|-----------|
+| **Atlas** | 1TB Storage | 4,000 MAD | 2,000 MAD | 2,000 MAD | 7 |
+| **Atlas+** | 1TB + Sauvegarde | 5,000 MAD | 2,800 MAD | 2,200 MAD | 9 |
+| **Rif** | 500GB Server | 3,500 MAD | 1,700 MAD | 1,800 MAD | 7 |
+| **Rif+** | 500GB + Sauvegarde | 4,500 MAD | 2,200 MAD | 2,300 MAD | 9 |
+
+## 🔧 Component-Level Pricing
+
+Each offer has a granular breakdown of costs and sell prices. Edit any component independently — totals auto-recompute:
+
+```
+HDD (1TB)    cost: 600 MAD  ×1  sell: 1,000 MAD  →  margin: 400 MAD
+RAM (16GB)   cost: 300 MAD  ×1  sell: 500 MAD    →  margin: 200 MAD
+CPU alloc    cost: 200 MAD  ×1  sell: 400 MAD    →  margin: 200 MAD
+Bandwidth    cost: 200 MAD  ×1  sell: 500 MAD    →  margin: 300 MAD
+Support      cost: 200 MAD  ×1  sell: 700 MAD    →  margin: 500 MAD
+────────────────────────────────────────────────────────────
+Total       cost: 2,000 MAD     sell: 4,000 MAD   margin: 2,000 MAD
+```
+
+## 🚀 Quick Start
+
+### Prerequisites
+- Python 3.11+
+- pip or uv
+
+### Install
+
+```bash
+# Clone
+git clone http://192.168.1.160:3000/fedora-heremes/vela-platform.git
+cd vela-platform
+
+# Install deps
+cd backend
+pip install -r requirements.txt
+
+# Run
+uvicorn main:app --host 0.0.0.0 --port 8788
+```
+
+The app auto-creates the database and seeds demo data on first run.
+
+### systemd (auto-start)
+
+```ini
+# ~/.config/systemd/user/vela-platform.service
+[Unit]
+Description=Vela Platform — P&L Tracking App
+
+[Service]
+ExecStart=%h/vela-platform/backend/venv/bin/uvicorn main:app --host 0.0.0.0 --port 8788
+WorkingDirectory=%h/vela-platform/backend
+Restart=always
+
+[Install]
+WantedBy=default.target
+```
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now vela-platform.service
+```
+
+## 👥 Users
+
+| User | Role | Password |
+|------|------|----------|
+| `admin` | Owner (full access) | `admin123` |
+| `viewer` | Read-only | `viewer123` |
+
+## 🔌 API
+
+All CRUD operations available via REST API. Authenticate with Bearer token.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/auth/login` | Login |
+| GET | `/api/services` | List offers + components |
+| POST | `/api/services/{id}/components` | Add component |
+| PUT | `/api/components/{id}` | Update component |
+| DELETE | `/api/components/{id}` | Delete component |
+| GET | `/api/transactions?month=YYYY-MM` | List transactions |
+| POST | `/api/transactions` | Add transaction |
+| GET | `/api/pnl?month=YYYY-MM` | P&L report |
+| GET | `/api/dashboard` | Overview + trend |
+
+## 🤖 MCP Integration
+
+Use with AI agents via MCP (Model Context Protocol). Tools available:
+- `get_services()` — Full offers with component breakdowns
+- `get_service(id)` — Single offer detail
+- `add_component(...)` — Add component to an offer
+- `update_component(...)` — Update a component
+- `delete_component(id)` — Delete a component
+- `add_transaction(...)` — Log a sale
+- `get_pnl(month)` — P&L for a month
+- `get_dashboard()` — Current overview
+
+## 🧱 Tech Stack
+
+- **Python 3** + **FastAPI** — API & web server
+- **SQLite** + **SQLAlchemy** — Database (zero config)
+- **Jinja2** + **Bootstrap 5** — Web UI (dark mode)
+- **Chart.js** — Trend charts
+- **JWT** — Auth (cookie + Bearer)
+- **MCP** — AI agent integration
+
+## 📄 License
+
+MIT