bonamin/bellsystems-cp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7183987924991ac9411c97252436bed522dd864a
bellsystems-cp/BellSystems_AdminPanel_Strategy.md
bonamin 30bcd2f9cd project initialization
2026-02-16 19:57:22 +02:00

311 lines
11 KiB
Markdown
Raw Blame History

# BellSystems Admin Panel — Strategy Guide
## Project Overview
A self-hosted web-based admin panel for managing BellSystems devices, melodies, users, and MQTT communications. Built with **Python (FastAPI)** backend and **React** frontend, deployed on a **VPS** behind **Nginx**.
---
## Deployment Architecture
```
[Browser] → [Nginx (VPS)]
├── / → React Frontend (static files)
└── /api → FastAPI Backend
├── Firestore (Google Cloud) via Admin SDK
├── Mosquitto (localhost on VPS)
└── Firebase Storage (for melody files)
```
**Everything lives on the VPS:**
- Nginx as reverse proxy + static file server
- FastAPI as the API backend
- Mosquitto MQTT broker (already running there)
- React frontend served as static files
- All containerized with Docker Compose
---
## Tech Stack
| Layer | Technology |
| ----------- | --------------------------------- |
| Frontend | React + Tailwind CSS + Vite |
| Backend | Python 3.11+ / FastAPI |
| Database | Firestore (via Firebase Admin SDK) |
| File Storage| Firebase Storage |
| MQTT | Mosquitto (local) + paho-mqtt |
| Auth | JWT (FastAPI) with role-based access |
| Deployment | Docker Compose + Nginx |
| VPS OS | Linux (existing VPS in Germany) |
---
## Project Folder Structure
```
bellsystems-admin/
├── docker-compose.yml
├── .env # Secrets (gitignored)
├── .env.example # Template for env vars
├── README.md
│
├── backend/
│ ├── Dockerfile
│ ├── requirements.txt
│ ├── main.py # FastAPI app entry point
│ ├── config.py # Settings / env loading
│ │
│ ├── auth/
│ │ ├── __init__.py
│ │ ├── router.py # Login / token endpoints
│ │ ├── models.py # User/token schemas
│ │ ├── dependencies.py # JWT verification, role checks
│ │ └── utils.py # Password hashing, token creation
│ │
│ ├── melodies/
│ │ ├── __init__.py
│ │ ├── router.py # CRUD endpoints for melodies
│ │ ├── models.py # Pydantic schemas
│ │ └── service.py # Firestore operations
│ │
│ ├── devices/
│ │ ├── __init__.py
│ │ ├── router.py # CRUD endpoints for devices
│ │ ├── models.py # Pydantic schemas
│ │ └── service.py # Firestore operations
│ │
│ ├── users/
│ │ ├── __init__.py
│ │ ├── router.py # CRUD endpoints for users
│ │ ├── models.py # Pydantic schemas
│ │ └── service.py # Firestore operations
│ │
│ ├── mqtt/
│ │ ├── __init__.py
│ │ ├── router.py # Command endpoints + WebSocket for live data
│ │ ├── client.py # MQTT client wrapper (paho-mqtt)
│ │ ├── logger.py # Log storage and retrieval
│ │ └── mosquitto.py # Mosquitto password file management
│ │
│ ├── equipment/
│ │ ├── __init__.py
│ │ ├── router.py # Complementary devices / notes
│ │ ├── models.py
│ │ └── service.py
│ │
│ └── shared/
│ ├── __init__.py
│ ├── firebase.py # Firebase Admin SDK initialization
│ └── exceptions.py # Custom error handlers
│
├── frontend/
│ ├── Dockerfile
│ ├── package.json
│ ├── vite.config.js
│ ├── tailwind.config.js
│ ├── index.html
│ │
│ └── src/
│ ├── main.jsx
│ ├── App.jsx
│ │
│ ├── api/
│ │ └── client.js # Axios/fetch wrapper with JWT
│ │
│ ├── auth/
│ │ ├── LoginPage.jsx
│ │ └── AuthContext.jsx # JWT token state management
│ │
│ ├── layout/
│ │ ├── Sidebar.jsx # Navigation menu
│ │ ├── Header.jsx
│ │ └── MainLayout.jsx
│ │
│ ├── melodies/
│ │ ├── MelodyList.jsx
│ │ ├── MelodyForm.jsx # Add / Edit form
│ │ └── MelodyDetail.jsx
│ │
│ ├── devices/
│ │ ├── DeviceList.jsx
│ │ ├── DeviceForm.jsx
│ │ └── DeviceDetail.jsx
│ │
│ ├── users/
│ │ ├── UserList.jsx
│ │ ├── UserForm.jsx
│ │ └── UserDetail.jsx
│ │
│ ├── mqtt/
│ │ ├── MqttDashboard.jsx # Live data, logs, charts
│ │ └── CommandPanel.jsx # Send commands to devices
│ │
│ └── components/
│ ├── DataTable.jsx # Reusable table component
│ ├── SearchBar.jsx
│ ├── ConfirmDialog.jsx
│ └── StatusBadge.jsx
│
└── nginx/
└── nginx.conf # Nginx reverse proxy config
```
---
## Auth & Roles
| Role | Access |
| --------------- | ------------------------------------------- |
| `superadmin` | Everything — full CRUD on all resources |
| `melody_editor` | Melodies: full CRUD |
| `device_manager`| Devices + MQTT: full CRUD + commands |
| `user_manager` | Users: full CRUD |
| `viewer` | Read-only access to everything |
Admin users are stored in a separate Firestore collection (`admin_users`) or a local database (SQLite/PostgreSQL). JWT tokens carry the role, and FastAPI dependencies enforce permissions per endpoint.
---
## Build Phases
### Phase 0 — Project Scaffolding
- [ ] Initialize backend (FastAPI project structure)
- [ ] Initialize frontend (React + Vite + Tailwind)
- [ ] Docker Compose setup (backend + frontend + nginx)
- [ ] Environment variables / config
- [ ] Firebase Admin SDK setup (service account key)
- [ ] Verify Firestore connectivity
### Phase 1 — Auth System
- [ ] Admin user model (Firestore or local DB)
- [ ] Login endpoint (email + password → JWT)
- [ ] JWT middleware for protected routes
- [ ] Role-based access control (RBAC) dependencies
- [ ] Login page (frontend)
- [ ] Auth context + protected routes (frontend)
### Phase 2 — Melody Editor (Priority #1)
- [ ] Firestore melody document schema review
- [ ] Backend: CRUD endpoints (list, get, create, update, delete)
- [ ] Backend: Firebase Storage integration (upload/manage bin files)
- [ ] Frontend: Melody list with search/filter
- [ ] Frontend: Add/Edit melody form (all attributes)
- [ ] Frontend: Delete with confirmation
- [ ] Frontend: File upload for online melodies
### Phase 3 — Device Editor
- [ ] Firestore device document schema review
- [ ] Backend: CRUD endpoints
- [ ] Backend: Serial number generation (unique)
- [ ] Backend: Mosquitto password registration (auto)
- [ ] Frontend: Device list with status indicators
- [ ] Frontend: Add/Edit device form
- [ ] Frontend: Delete with confirmation
### Phase 4 — User Editor
- [ ] Firestore user document schema review
- [ ] Backend: CRUD endpoints
- [ ] Backend: User-device assignment management
- [ ] Frontend: User list with search/filter
- [ ] Frontend: Add/Edit user form
- [ ] Frontend: Block/unblock functionality
- [ ] Frontend: Device assignment UI
### Phase 5 — MQTT Integration
- [ ] Backend: MQTT client (paho-mqtt) connecting to Mosquitto
- [ ] Backend: Send commands to devices via MQTT
- [ ] Backend: Receive and store device logs/heartbeats
- [ ] Backend: WebSocket endpoint for live MQTT data streaming
- [ ] Frontend: MQTT dashboard (live device status)
- [ ] Frontend: Command panel (send commands)
- [ ] Frontend: Log viewer with filtering
- [ ] Frontend: Basic charts/histograms (playback events, etc.)
### Phase 6 — Equipment & Notes Tracking
- [ ] Backend: CRUD for complementary equipment notes
- [ ] Frontend: Simple note/log interface per device/user
### Phase 7 — Polish & Deployment
- [ ] SSL certificates (Let's Encrypt via Certbot)
- [ ] Production Docker Compose config
- [ ] Nginx hardening
- [ ] Backup strategy for logs/data
- [ ] Error handling & loading states (frontend)
- [ ] Mobile responsiveness (basic)
---
## Key Decisions
| Decision | Choice | Reason |
| -------------------------- | -------------------------------- | -------------------------------------------- |
| Backend framework | FastAPI | Easy to learn, async, auto-docs |
| Frontend framework | React | Huge ecosystem, great for admin UIs |
| CSS framework | Tailwind CSS | Fast styling, no custom CSS needed |
| Build tool | Vite | Fast dev server, instant HMR |
| MQTT library | paho-mqtt (Python) | Standard, reliable, well-documented |
| Mosquitto auth | Password file (direct management)| Simple, no plugins needed |
| Deployment | Docker Compose on VPS | Single server, easy to manage |
| Admin auth storage | Firestore `admin_users` collection| Consistent with existing data layer |
---
## Environment Variables (.env)
```env
# Firebase
FIREBASE_SERVICE_ACCOUNT_PATH=./firebase-service-account.json
# JWT
JWT_SECRET_KEY=your-secret-key-here
JWT_ALGORITHM=HS256
JWT_EXPIRATION_MINUTES=480
# MQTT
MQTT_BROKER_HOST=localhost
MQTT_BROKER_PORT=1883
MQTT_ADMIN_USERNAME=admin
MQTT_ADMIN_PASSWORD=your-mqtt-admin-password
MOSQUITTO_PASSWORD_FILE=/etc/mosquitto/passwd
# App
BACKEND_CORS_ORIGINS=["http://localhost:5173"]
DEBUG=true
```
---
## First Steps for Claude Code
Once this strategy is reviewed and approved, the first command for Claude Code:
```
Initialize the bellsystems-admin project:
1. Create the folder structure as defined in the strategy guide
2. Set up the backend with FastAPI (main.py, config.py, requirements.txt)
3. Set up the frontend with React + Vite + Tailwind
4. Create docker-compose.yml with backend, frontend, and nginx services
5. Create the nginx.conf for reverse proxying
6. Create .env.example with all required variables
7. Wire up Firebase Admin SDK initialization (backend/shared/firebase.py)
8. Create a basic health-check endpoint to verify everything runs
```
---
## Notes
- All Firestore document schemas will be reviewed together before building each module
- MQTT log storage strategy (local DB vs Firestore) to be decided in Phase 5
- The existing Flutter app (main product) remains unchanged — this admin panel is a separate tool
- OTA update management could be added as a future phase
Reference in New Issue View Git Blame Copy Permalink