project initialization
This commit is contained in:
311
BellSystems_AdminPanel_Strategy.md
Normal file
311
BellSystems_AdminPanel_Strategy.md
Normal file
@@ -0,0 +1,311 @@
|
||||
# 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
Block a user