Olaf
b5f5f30005
- add period-scoped holiday architecture end-to-end - model: scope `SchoolHoliday` to `academic_period_id` - migrations: add holiday-period scoping, academic-period archive lifecycle, and merge migration head - API: extend holidays with manual CRUD, period validation, duplicate prevention, and overlap merge/conflict handling - recurrence: regenerate holiday exceptions using period-scoped holiday sets - improve frontend settings and holiday workflows - bind holiday import/list/manual CRUD to selected academic period - show detailed import outcomes (inserted/updated/merged/skipped/conflicts) - fix file-picker UX (visible selected filename) - align settings controls/dialogs with defined frontend design rules - scope appointments/dashboard holiday loading to active period - add shared date formatting utility - strengthen academic period lifecycle handling - add archive/restore/delete flow and backend validations/blocker checks - extend API client support for lifecycle operations - release/docs updates and cleanup - bump user-facing version to `2026.1.0-alpha.15` with new changelog entry - add tech changelog entry for alpha.15 backend changes - refactor README to concise index and archive historical implementation docs - fix Copilot instruction link diagnostics via local `.github` design-rules reference
187 lines
5.7 KiB
Markdown
187 lines
5.7 KiB
Markdown
# Infoscreen 2025
|
|
|
|
[](https://www.docker.com/)
|
|
[](https://reactjs.org/)
|
|
[](https://flask.palletsprojects.com/)
|
|
[](https://mariadb.org/)
|
|
[](https://mosquitto.org/)
|
|
|
|
Multi-service digital signage platform for educational institutions.
|
|
|
|
Core stack:
|
|
- Dashboard: React + Vite + Syncfusion
|
|
- API: Flask + SQLAlchemy + Alembic
|
|
- DB: MariaDB
|
|
- Messaging: MQTT (Mosquitto)
|
|
- Background jobs: Redis + RQ + Gotenberg
|
|
|
|
## Architecture (Short)
|
|
|
|
- Dashboard talks only to API (`/api/...` via Vite proxy in dev).
|
|
- API is the single writer to MariaDB.
|
|
- Listener consumes MQTT discovery/heartbeat/log/screenshot topics and updates API state.
|
|
- Scheduler expands recurring events, applies exceptions, and publishes active content to retained MQTT topics.
|
|
- Worker handles document conversions asynchronously.
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
- Docker + Docker Compose
|
|
- Git
|
|
|
|
### Development
|
|
|
|
1. Clone
|
|
```bash
|
|
git clone https://github.com/RobbStarkAustria/infoscreen_2025.git
|
|
cd infoscreen_2025
|
|
```
|
|
|
|
2. Configure environment
|
|
```bash
|
|
cp .env.example .env
|
|
# edit values as needed
|
|
```
|
|
|
|
3. Start stack
|
|
```bash
|
|
make up
|
|
# or: docker compose up -d --build
|
|
```
|
|
|
|
4. Initialize DB (first run)
|
|
```bash
|
|
python server/initialize_database.py
|
|
```
|
|
|
|
5. Open services
|
|
- Dashboard: http://localhost:5173
|
|
- API: http://localhost:8000
|
|
- MariaDB: localhost:3306
|
|
- MQTT: localhost:1883 (WS: 9001)
|
|
|
|
## Holiday Calendar (Quick Usage)
|
|
|
|
Settings path:
|
|
- `Settings` -> `Academic Calendar` -> `Ferienkalender: Import/Anzeige`
|
|
|
|
Workflow summary:
|
|
1. Select target academic period (archived periods are read-only/not selectable).
|
|
2. Import CSV/TXT or add/edit holidays manually.
|
|
3. Validation is period-scoped (out-of-period ranges are blocked).
|
|
4. Duplicate/overlap policy:
|
|
- exact duplicates: skipped/prevented
|
|
- same normalized `name+region` overlaps (including adjacent ranges): merged
|
|
- different-identity overlaps: conflict (manual blocked, import skipped with details)
|
|
5. Recurring events with `skip_holidays` are recalculated automatically after holiday changes.
|
|
|
|
## Common Commands
|
|
|
|
```bash
|
|
# Start/stop
|
|
make up
|
|
make down
|
|
|
|
# Logs
|
|
make logs
|
|
make logs-server
|
|
|
|
# Health
|
|
make health
|
|
|
|
# Build/push/deploy
|
|
make build
|
|
make push
|
|
make pull-prod
|
|
make up-prod
|
|
```
|
|
|
|
## Documentation Map
|
|
|
|
### Deployment
|
|
- [deployment-debian.md](deployment-debian.md)
|
|
- [deployment-ubuntu.md](deployment-ubuntu.md)
|
|
- [setup-deployment.sh](setup-deployment.sh)
|
|
|
|
### Backend & Database
|
|
- [DATABASE_GUIDE.md](DATABASE_GUIDE.md)
|
|
- [TECH-CHANGELOG.md](TECH-CHANGELOG.md)
|
|
- [server/alembic](server/alembic)
|
|
|
|
### Authentication & Authorization
|
|
- [AUTH_SYSTEM.md](AUTH_SYSTEM.md)
|
|
- [AUTH_QUICKREF.md](AUTH_QUICKREF.md)
|
|
- [userrole-management.md](userrole-management.md)
|
|
- [SUPERADMIN_SETUP.md](SUPERADMIN_SETUP.md)
|
|
|
|
### Monitoring, Screenshots, Health
|
|
- [CLIENT_MONITORING_IMPLEMENTATION_GUIDE.md](CLIENT_MONITORING_IMPLEMENTATION_GUIDE.md)
|
|
- [CLIENT_MONITORING_SPECIFICATION.md](CLIENT_MONITORING_SPECIFICATION.md)
|
|
- [SCREENSHOT_IMPLEMENTATION.md](SCREENSHOT_IMPLEMENTATION.md)
|
|
|
|
### MQTT & Payloads
|
|
- [MQTT_EVENT_PAYLOAD_GUIDE.md](MQTT_EVENT_PAYLOAD_GUIDE.md)
|
|
- [MQTT_PAYLOAD_MIGRATION_GUIDE.md](MQTT_PAYLOAD_MIGRATION_GUIDE.md)
|
|
|
|
### Events, Calendar, WebUntis
|
|
- [WEBUNTIS_EVENT_IMPLEMENTATION.md](WEBUNTIS_EVENT_IMPLEMENTATION.md)
|
|
|
|
### Historical Background
|
|
- [docs/archive/ACADEMIC_PERIODS_IMPLEMENTATION_SUMMARY.md](docs/archive/ACADEMIC_PERIODS_IMPLEMENTATION_SUMMARY.md)
|
|
- [docs/archive/ACADEMIC_PERIODS_CRUD_BUILD_PLAN.md](docs/archive/ACADEMIC_PERIODS_CRUD_BUILD_PLAN.md)
|
|
- [docs/archive/PHASE_3_CLIENT_MONITORING_IMPLEMENTATION.md](docs/archive/PHASE_3_CLIENT_MONITORING_IMPLEMENTATION.md)
|
|
- [docs/archive/CLEANUP_SUMMARY.md](docs/archive/CLEANUP_SUMMARY.md)
|
|
|
|
### Conversion / Media
|
|
- [pptx_conversion_guide.md](pptx_conversion_guide.md)
|
|
- [pptx_conversion_guide_gotenberg.md](pptx_conversion_guide_gotenberg.md)
|
|
|
|
### Frontend
|
|
- [FRONTEND_DESIGN_RULES.md](FRONTEND_DESIGN_RULES.md)
|
|
- [dashboard/README.md](dashboard/README.md)
|
|
|
|
### Project / Contributor Guidance
|
|
- [.github/copilot-instructions.md](.github/copilot-instructions.md)
|
|
- [AI-INSTRUCTIONS-MAINTENANCE.md](AI-INSTRUCTIONS-MAINTENANCE.md)
|
|
- [DEV-CHANGELOG.md](DEV-CHANGELOG.md)
|
|
|
|
## API Highlights
|
|
|
|
- Core resources: clients, groups, events, academic periods
|
|
- Holidays: `GET/POST /api/holidays`, `POST /api/holidays/upload`, `PUT/DELETE /api/holidays/<id>`
|
|
- Media: upload/download/stream + conversion status
|
|
- Auth: login/logout/change-password
|
|
- Monitoring: logs and monitoring overview endpoints
|
|
|
|
For full endpoint details, use source route files under `server/routes/` and the docs listed above.
|
|
|
|
## Project Structure (Top Level)
|
|
|
|
```text
|
|
infoscreen_2025/
|
|
├── dashboard/ # React frontend
|
|
├── server/ # Flask API + migrations + worker
|
|
├── listener/ # MQTT listener
|
|
├── scheduler/ # Event scheduler/publisher
|
|
├── models/ # Shared SQLAlchemy models
|
|
├── mosquitto/ # MQTT broker config
|
|
├── certs/ # TLS certs (prod)
|
|
└── docker-compose*.yml
|
|
```
|
|
|
|
## Contributing
|
|
|
|
1. Create branch
|
|
2. Implement change + tests
|
|
3. Update relevant docs
|
|
4. Open PR
|
|
|
|
Guidelines:
|
|
- Match existing architecture and naming conventions
|
|
- Keep frontend aligned with [FRONTEND_DESIGN_RULES.md](FRONTEND_DESIGN_RULES.md)
|
|
- Keep service/API behavior aligned with [.github/copilot-instructions.md](.github/copilot-instructions.md)
|
|
|
|
## License
|
|
|
|
MIT License. See [LICENSE](LICENSE).
|