From 30bcd2f9cdc8ba1cb8bf7ec6e9cc3cc99dc2e033 Mon Sep 17 00:00:00 2001 From: bonamin Date: Mon, 16 Feb 2026 19:57:22 +0200 Subject: [PATCH] project initialization --- .gitignore | 7 + BellSystems_AdminPanel_Strategy.md | 311 +++++++++++++++++++++++++++++ README.md | 44 ++++ 3 files changed, 362 insertions(+) create mode 100644 .gitignore create mode 100644 BellSystems_AdminPanel_Strategy.md create mode 100644 README.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..26fa5a9 --- /dev/null +++ b/.gitignore @@ -0,0 +1,7 @@ +.env +firebase-service-account.json +node_modules/ +__pycache__/ +*.pyc +.venv/ +dist/ \ No newline at end of file diff --git a/BellSystems_AdminPanel_Strategy.md b/BellSystems_AdminPanel_Strategy.md new file mode 100644 index 0000000..ff6efc4 --- /dev/null +++ b/BellSystems_AdminPanel_Strategy.md @@ -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 \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..f97559a --- /dev/null +++ b/README.md @@ -0,0 +1,44 @@ +# BellSystems Admin Panel + +Self-hosted web admin panel for managing BellSystems devices, melodies, users, and MQTT communications. + +## Tech Stack + +- **Backend:** Python / FastAPI +- **Frontend:** React + Tailwind CSS (Vite) +- **Database:** Google Firestore (Firebase Admin SDK) +- **MQTT:** Mosquitto (paho-mqtt) +- **Auth:** JWT with role-based access control +- **Deployment:** Docker Compose + Nginx + +## Getting Started + +```bash +# Clone the repo +git clone /bellsystems-admin.git +cd bellsystems-admin + +# Copy env template and fill in your values +cp .env.example .env + +# Place your Firebase service account key in the project root +# (file is gitignored — never commit it) + +# Start everything +docker compose up --build +``` + +## Project Structure + +``` +bellsystems-admin/ +├── backend/ # FastAPI API server +├── frontend/ # React SPA +├── nginx/ # Reverse proxy config +├── docker-compose.yml +└── .env +``` + +## Documentation + +See `BellSystems_AdminPanel_Strategy.md` for the full architecture and build plan. \ No newline at end of file