How tezay/mariam works
1. Overall shape
- MARIAM is a two-tier application: a React/Vite frontend in client/ and a Flask REST backend in server/.
- The frontend serves both public menu consumption and admin management, while the backend owns authentication, business rules, persistence, and file storage.
2. Frontend boundary
- client/src/pages/public/* contains the unauthenticated experience: menu display, notifications page, mobile and TV variants.
- client/src/pages/admin/* contains the authenticated back-office: weekly planner, calendar views, events, gallery, users, settings, closures, and installation/transfer flows.
- Shared UI is concentrated in client/src/components/ plus a local UI kit in client/src/components/ui/.
3. Frontend data access and session state
- client/src/lib/api.ts is the main API client boundary; it centralizes HTTP calls to the backend.
- AuthContext manages login/session state, while ThemeProvider and PwaInstallContext handle cross-cutting client concerns.
- The client also includes push/PWA support via client/src/lib/push.ts and client/src/sw-push.js, which ties into browser notifications.
4. Backend domain boundary
- The Flask app is organized by feature under server/app/routes/, with modules for auth, menus, events, gallery, users, restaurant, categories, closures, imports, notifications, audit, and taxonomy.
- server/app/models/ contains the persistence model layer for those same business concepts.
- server/app/schemas/ provides request/response validation and serialization, which separates API contracts from ORM models.
5. Core business flows
- Menu authoring flow: admins create/edit weekly and daily menus in the frontend, which maps to backend menu/category/event endpoints and persists to PostgreSQL.
- Publication flow: once content is ready, the backend exposes it to public menu pages without authentication.
- Event and closure flow: special events and exceptional closures are managed separately from standard menus and shown in public display views.
- Gallery flow: uploaded images are stored in S3-compatible storage and reused across menu items and events.
6. Authentication and security model
- Admin access is protected by JWT-based API auth plus stronger identity features: MFA/TOTP and passkeys are both present in the model and routes.
- Account lifecycle includes activation and password reset paths on the client (Activate, ResetPassword) and corresponding backend routes.
- server/app/security.py plus the auth routes are the main security boundary; server/app/models/audit_log.py supports traceability of sensitive actions.
7. Storage and persistence
- PostgreSQL is the primary system of record for users, restaurant configuration, menus, events, closures, imports, audit logs, passkeys, and subscriptions.
- S3-compatible object storage is a second persistence tier for images and uploaded assets; server/app/services/storage.py encapsulates bucket management, upload, and deletion.
- The README and file structure indicate separate prefixes for gallery images, event images, menu images, and restaurant logos, which is important when drawing the storage boundary.
8. Taxonomy and content metadata
- The repo treats food tags/certifications as structured domain data rather than free text.
- server/app/data/taxonomy.py and server/app/models/taxonomy.py back a controlled vocabulary used by the frontend for labels, icons, and filtering.
- This taxonomy is central to the public menu UX because the menus surface dietary tags and certifications as first-class metadata.
9. Notifications and PWA behavior
- server/app/models/push_subscription.py and server/app/services/notification_service.py support browser push notifications.
- The client includes install and push-related contexts/pages, indicating a PWA-style experience for admins and/or students.
- Public notification pages are part of the frontend, but actual delivery is driven by backend subscriptions and notification service logic.
10. Deployment topology
- Development is containerized with Docker Compose at the repository root.
- Production is split under deploy/, with Nginx configuration, install/run scripts, and a separate compose setup.
- The README shows the intended runtime stack: frontend on port 5173, Flask API on 5000, PostgreSQL on 5432, and MinIO/S3 on 9000/9001 in development.
11. Schema evolution and maintenance
- server/migrations/ uses Alembic for database versioning, which is the durable contract for schema changes.
- server/app/commands/ and server/app/scripts/ contain operational commands such as seeding, demo data, and migration execution.
- This means operational setup is not just “run the app”; there is an explicit provisioning path for the first restaurant/admin account and for database initialization.
12. Quality and test boundaries
- The backend has pytest coverage in server/tests/, focused on auth, categories, menus, public menu behavior, restaurant, and users.
- The frontend has unit tests under client/src/__tests__/.
- CI/CD is split into quality and publish workflows in .github/workflows/, so code quality and container publishing are part of the delivery architecture.
13. How to draw the diagram
- Show public clients and admin clients as the same frontend application with different route groups and capabilities.
- Draw the Flask API as the central business layer, with separate feature modules behind it.
- Connect the API to PostgreSQL for structured data and to S3/MinIO for images and uploads.
- Mark auth/MFA, push notifications, and taxonomy as cross-cutting subdomains rather than separate apps.
Main entry points: admin Admin pages · models Models · schemas Schemas · App.tsx Client app
Components 20
Client app
React/Vite frontend for public menu viewing and admin operations.
- Client app · Single-page frontend with public and admin route groups.
client/src/App.tsx - Public pages · Unauthenticated menu, notifications, mobile, and TV experiences.
client/src/pages/public - Admin pages · Authenticated management for menus, calendar, users, settings, and setup flows.
client/src/pages/admin - Shared UI · Reusable layouts, editors, pickers, and the local UI kit.
client/src/components - Client state · Auth, theme, PWA install state, API access, and push helpers.
client/src/contexts - Browser push · Client-side notification and install surfaces tied to push subscriptions.
client/src/lib/push.ts
Flask API
Server-side API, domain logic, persistence, and services.
- Auth API · Login, activation, password reset, MFA, and passkey flows.
server/app/routes/auth.py - Menu API · Weekly and daily menu publishing and editing endpoints.
server/app/routes/menus.py - Calendar API · Events, closures, and calendar-oriented content endpoints.
server/app/routes/events.py - Content API · Gallery, categories, taxonomy, restaurant, and import endpoints.
server/app/routes/gallery.py - Admin API · Users, audit logging, notifications, and operational administration endpoints.
server/app/routes/users.py - Models · Persistence layer for users, menus, events, closures, gallery, taxonomy, and subscriptions.
server/app/models - Schemas · Request and response validation plus serialization boundaries.
server/app/schemas - Security · Shared security boundary for JWT auth, MFA/TOTP, and passkeys.
server/app/security.py - Services · Notification delivery and object storage integration.
server/app/services - Taxonomy data · Structured tags and certifications used for menu labeling and filtering.
server/app/data/taxonomy.py
Delivery
Deployment, migrations, scripts, and CI/CD surfaces.
- Deploy stack · Compose, Nginx, and production scripts for running the system.
deploy/docker-compose.yml - Migrations · Database schema versioning and upgrade history.
server/migrations
External systems
Runtime persistence and infrastructure dependencies.
- PostgreSQL · Primary system of record for business entities and audit history.
- S3 storage · Image and asset storage for gallery, menu, event, and logo uploads.
Connections 31
- Client app → Public pages: routes · Public navigation and unauthenticated experiences.
- Client app → Admin pages: routes · Authenticated back-office routes and views.
- Client app → Shared UI: uses · Shared UI and editor primitives.
- Client app → Client state: state · Auth, theme, install, API, and session helpers.
- Public pages → Menu API: reads · Fetches published menus and public content.
- Admin pages → Auth API: auth · Login, activation, reset, MFA, and passkey flows.
- Admin pages → Menu API: edits · Creates and updates menus and weekly planning data.
- Admin pages → Calendar API: manages · Schedules events and closures through calendar workflows.
- Admin pages → Content API: manages · Uses gallery, category, taxonomy, restaurant, and import APIs.
- Admin pages → Admin API: admin · User, audit, notification, and setup operations.
- Client state → Browser push: push · Install and browser notification support.
- Auth API → Security: enforces · Shared authentication and authorization boundary.
- Auth API → Models: persists · Users, activation links, passkeys, and audit-related state.
- Menu API → Models: persists · Menus, categories, and publication state.
- Calendar API → Models: persists · Events and exceptional closures.
- Content API → Models: persists · Gallery, restaurant, taxonomy, category, and import data.
- Admin API → Models: persists · Users, notifications, audit logs, and subscriptions.
- Schemas → Auth API: validates · API contracts for auth endpoints.
- Schemas → Menu API: validates · API contracts for menu endpoints.
- Schemas → Calendar API: validates · API contracts for events and closures.
- Schemas → Content API: validates · API contracts for gallery, restaurant, taxonomy, and imports.
- Schemas → Admin API: validates · API contracts for users, audit, and notifications.
- Models → PostgreSQL: stores · Primary relational persistence.
- Services → S3 storage: uploads · Image and asset bucket management.
- Services → Browser push: delivers · Notification service supports browser push.
- Taxonomy data → Content API: feeds · Controlled vocabulary exposed through taxonomy APIs.
- Deploy stack → Client app: runs · Frontend container and Nginx delivery.
- Deploy stack → Auth API: runs · Backend container and API runtime.
- Deploy stack → PostgreSQL: depends · PostgreSQL runtime dependency.
- Deploy stack → S3 storage: depends · S3-compatible storage dependency.
- Migrations → PostgreSQL: upgrades · Schema versioning for PostgreSQL.