# mbmuniversity2026/mac architecture

> Architecture diagram of the GitHub repository mbmuniversity2026/mac, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mbmuniversity2026/mac
- Repository: https://github.com/mbmuniversity2026/mac

## Overview

1. **Overall shape**
   - MAC is a **single FastAPI backend** plus a **static browser frontend**, deployed together with **Nginx** and supporting infrastructure in **Docker Compose**.
   - The architecture is centered on the campus LAN: the browser talks to Nginx, which serves the frontend and proxies API/WebSocket traffic to the Python app.

2. **Frontend boundary**
   - `frontend/` is a **vanilla JS SPA** with no build pipeline or Node runtime.
   - It is split into feature pages/modules such as chat, notebooks, doubts, attendance, file sharing, admin, settings, shell, and notifications.
   - The frontend also includes a **PWA service worker**, offline i18n assets, and vendored **Monaco Editor** libraries for notebook/code editing.

3. **API layer**
   - `mac/routers/` is the public surface of the system: REST endpoints and WebSocket endpoints for auth, notebooks, chat/query, RAG, files, nodes, quota, system/admin, search, attendance, models, video, voice chat, and more.
   - `mac/routers/notebook_ws.py` and `mac/routers/terminal.py` indicate long-lived interactive channels, not just request/response APIs.

4. **Domain/service layer**
   - `mac/services/` contains the core business logic and orchestration.
   - Important service areas include **authentication**, **feature flags**, **quota/usage**, **node discovery and load balancing**, **kernel management**, **model management**, **RAG**, **search**, **copy check**, **attendance**, **notifications**, and **system setup**.
   - This is where the backend coordinates between database state, caches, inference nodes, and external integrations.

5. **Persistence model**
   - `mac/models/` and `mac/schemas/` define the backend’s data contract and ORM layer.
   - The repo uses **PostgreSQL** as the primary persistent store, with Alembic migrations tracking schema evolution.
   - Domain tables cover users, notebooks, doubts, attendance, file shares, nodes/clusters, models, quotas, feature flags, guardrails, RAG, notifications, and system configuration.

6. **Stateful infrastructure**
   - **Redis** is used for short-lived operational state rather than primary records: rate limiting, token blacklist, session-like coordination, and other transient backend workflows.
   - **Qdrant** stores vector embeddings for retrieval-augmented features.
   - **SearXNG** provides search aggregation for the search/explore subsystem.

7. **AI inference and retrieval path**
   - Chat and RAG are the main AI flows.
   - A request typically goes from the browser to chat/query or notebook endpoints, into service logic, then to a model/inference layer via **vLLM or Ollama** nodes.
   - When file context is attached, the backend routes content into the **RAG pipeline**, which likely indexes or queries vectors in Qdrant before assembling the prompt/context for the model.

8. **Distributed node / worker boundary**
   - The presence of `worker_agent.py`, `docker-compose.worker.yml`, and services like `node_service`, `cluster`, `load_balancer`, `discovery`, and `kernel_registry` suggests the platform supports **separate worker or GPU nodes**.
   - These nodes are managed as part of a campus-local cluster for model serving, notebook execution, or other compute-heavy tasks.
   - That makes the system more than a single-server app: there is a control plane in the main FastAPI service and a worker sidecar/agent layer for distributed execution.

9. **Security and policy enforcement**
   - `mac/middleware/` applies cross-cutting controls before requests reach business logic: **JWT authentication**, **feature gating**, and **rate limiting**.
   - Role-based access is built into the platform, with student/faculty/admin distinctions reflected in routes, services, and feature visibility.
   - There are dedicated services for scoped keys, token blacklisting, guardrails, and setup/bootstrap flows.

10. **Operational/admin subsystem**
   - The admin and system routers expose platform management: users, feature flags, quotas, nodes, hardware/network info, usage, integration, and setup.
   - This is where the platform is configured after deployment and where operators monitor health and campus-specific policy state.

11. **Interactive learning subsystems**
   - Beyond chat, the repo supports **MBM Book notebooks**, **doubts forum**, **attendance**, **copy check**, **file sharing**, and **notifications** as first-class application modules.
   - These features share the same auth, persistence, and admin foundations, but each has its own router/service/model slice.

12. **Deployment and runtime**
   - `docker-compose.yml`, `Dockerfile`, and `nginx/` define the runtime packaging.
   - Alembic manages database migration history.
   - CI/release workflows are present, so the repo is organized for repeatable deployment rather than ad hoc local runs.

13. **What to draw as the main diagram**
   - The key diagram should show: **Browser/PWA → Nginx → FastAPI backend → PostgreSQL/Redis/Qdrant/SearXNG + LLM nodes/workers**.
   - Around the backend, separate the major application domains: **Auth/Security**, **Chat/RAG**, **Notebooks/Terminal**, **Academic tools**, **Admin/System**, and **Node/Cluster management**.

Main entry points: [`mac/routers`](https://github.com/mbmuniversity2026/mac/tree/master/mac/routers) (API Routers), [`mac/services/rag_service.py`](https://github.com/mbmuniversity2026/mac/blob/master/mac/services/rag_service.py) (Chat & RAG), [`mac/services/notebook_service.py`](https://github.com/mbmuniversity2026/mac/blob/master/mac/services/notebook_service.py) (Notebooks), [`mac/services/auth_service.py`](https://github.com/mbmuniversity2026/mac/blob/master/mac/services/auth_service.py) (Auth & Security)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_browser["Browser PWA<br/>vanilla SPA<br/>[index.html]"]
  node_frontend_modules["Frontend Modules<br/>feature pages"]
  node_frontend_sw["Service Worker<br/>PWA offline<br/>[sw.js]"]
end

subgraph group_edge["Edge"]
  node_nginx["Nginx<br/>reverse proxy<br/>[nginx.conf]"]
end

subgraph group_backend["Backend"]
  node_fastapi["FastAPI App<br/>python backend<br/>[main.py]"]
  node_middleware["Middleware<br/>security gates"]
  node_routers["API Routers<br/>REST/WebSocket surface"]
  node_notebook_ws(("Notebook WS<br/>interactive channel<br/>[notebook_ws.py]"))
  node_terminal_ws(("Terminal WS<br/>interactive channel<br/>[terminal.py]"))
end

subgraph group_services["Services"]
  node_auth_sec["Auth & Security<br/>identity/policy<br/>[auth_service.py]"]
  node_chat_rag["Chat & RAG<br/>ai orchestration<br/>[rag_service.py]"]
  node_notebooks["Notebooks<br/>execution management"]
  node_nodes_cluster["Nodes & Cluster<br/>control plane<br/>[node_service.py]"]
  node_models_llm["Models & LLM<br/>model serving<br/>[model_service.py]"]
  node_academic_tools["Academic Tools<br/>app domain"]
  node_admin_ops["Admin & Setup<br/>ops/control<br/>[setup_service.py]"]
end

subgraph group_data["Data"]
  node_postgres[("PostgreSQL<br/>primary database")]
  node_redis[("Redis<br/>transient state")]
  node_qdrant[("Qdrant<br/>vector store")]
  node_searxng["SearXNG<br/>search backend"]
end

subgraph group_worker["Workers"]
  node_worker_agent(("Worker Agent<br/>distributed worker<br/>[worker_agent.py]"))
  node_llm_nodes["LLM Nodes<br/>vLLM/Ollama"]
end

node_browser -->|"HTTPS"| node_nginx
node_frontend_modules -->|"runs in"| node_browser
node_frontend_sw -.->|"caches"| node_browser
node_nginx -->|"proxies API"| node_fastapi
node_fastapi -->|"applies"| node_middleware
node_middleware -->|"guards"| node_routers
node_routers -->|"delegates"| node_auth_sec
node_routers -->|"delegates"| node_chat_rag
node_routers -->|"delegates"| node_notebooks
node_routers -->|"delegates"| node_nodes_cluster
node_routers -->|"delegates"| node_models_llm
node_routers -->|"delegates"| node_academic_tools
node_routers -->|"delegates"| node_admin_ops
node_notebook_ws -->|"feeds"| node_notebooks
node_terminal_ws -->|"feeds"| node_notebooks
node_auth_sec -->|"reads/writes"| node_postgres
node_chat_rag -->|"queries"| node_qdrant
node_chat_rag -->|"searches"| node_searxng
node_chat_rag -->|"invokes"| node_llm_nodes
node_notebooks -->|"reads/writes"| node_postgres
node_nodes_cluster -->|"reads/writes"| node_postgres
node_admin_ops -.->|"uses"| node_redis
node_auth_sec -.->|"uses"| node_redis
node_worker_agent -->|"reports to"| node_nodes_cluster
node_worker_agent -->|"hosts"| node_llm_nodes

click node_browser "https://github.com/mbmuniversity2026/mac/blob/master/frontend/index.html"
click node_frontend_modules "https://github.com/mbmuniversity2026/mac/tree/master/frontend/js"
click node_frontend_sw "https://github.com/mbmuniversity2026/mac/blob/master/frontend/sw.js"
click node_nginx "https://github.com/mbmuniversity2026/mac/blob/master/nginx/nginx.conf"
click node_fastapi "https://github.com/mbmuniversity2026/mac/blob/master/mac/main.py"
click node_middleware "https://github.com/mbmuniversity2026/mac/tree/master/mac/middleware"
click node_routers "https://github.com/mbmuniversity2026/mac/tree/master/mac/routers"
click node_notebook_ws "https://github.com/mbmuniversity2026/mac/blob/master/mac/routers/notebook_ws.py"
click node_terminal_ws "https://github.com/mbmuniversity2026/mac/blob/master/mac/routers/terminal.py"
click node_auth_sec "https://github.com/mbmuniversity2026/mac/blob/master/mac/services/auth_service.py"
click node_chat_rag "https://github.com/mbmuniversity2026/mac/blob/master/mac/services/rag_service.py"
click node_notebooks "https://github.com/mbmuniversity2026/mac/blob/master/mac/services/notebook_service.py"
click node_nodes_cluster "https://github.com/mbmuniversity2026/mac/blob/master/mac/services/node_service.py"
click node_models_llm "https://github.com/mbmuniversity2026/mac/blob/master/mac/services/model_service.py"
click node_academic_tools "https://github.com/mbmuniversity2026/mac/blob/master/mac/services/attendance_service.py"
click node_admin_ops "https://github.com/mbmuniversity2026/mac/blob/master/mac/services/setup_service.py"
click node_postgres "https://github.com/mbmuniversity2026/mac/blob/master/alembic/versions/20260426_0001_initial_schema.py"
click node_worker_agent "https://github.com/mbmuniversity2026/mac/blob/master/worker_agent.py"
click node_llm_nodes "https://github.com/mbmuniversity2026/mac/blob/master/docker-compose.worker.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser,node_frontend_modules,node_frontend_sw toneBlue
class node_nginx toneAmber
class node_fastapi,node_middleware,node_routers,node_notebook_ws,node_terminal_ws toneMint
class node_auth_sec,node_chat_rag,node_notebooks,node_nodes_cluster,node_models_llm,node_academic_tools,node_admin_ops toneRose
class node_postgres,node_redis,node_qdrant,node_searxng toneIndigo
class node_worker_agent,node_llm_nodes toneTeal
```

## Components

### Client

Browser-facing UI and offline assets.

- [Browser PWA](https://github.com/mbmuniversity2026/mac/blob/master/frontend/index.html): vanilla SPA · Static campus browser UI with offline support and feature pages. · `frontend/index.html`
- [Frontend Modules](https://github.com/mbmuniversity2026/mac/tree/master/frontend/js): feature pages · Chat, notebooks, doubts, attendance, files, admin, settings, shell, notifications. · `frontend/js`
- [Service Worker](https://github.com/mbmuniversity2026/mac/blob/master/frontend/sw.js): PWA offline · Offline caching and app-shell support for the frontend. · `frontend/sw.js`

### Edge

Deployment and request entrypoint.

- [Nginx](https://github.com/mbmuniversity2026/mac/blob/master/nginx/nginx.conf): reverse proxy · Serves the static frontend and proxies API/WebSocket traffic. · `nginx/nginx.conf`

### Backend

FastAPI application surface and orchestration.

- [FastAPI App](https://github.com/mbmuniversity2026/mac/blob/master/mac/main.py): python backend · Main application entrypoint and request lifecycle. · `mac/main.py`
- [Middleware](https://github.com/mbmuniversity2026/mac/tree/master/mac/middleware): security gates · JWT auth, feature gating, and rate limiting before routes. · `mac/middleware`
- [API Routers](https://github.com/mbmuniversity2026/mac/tree/master/mac/routers): REST/WebSocket surface · Public endpoints for auth, chat, notebooks, RAG, files, nodes, admin, search, and more. · `mac/routers`
- [Notebook WS](https://github.com/mbmuniversity2026/mac/blob/master/mac/routers/notebook_ws.py): interactive channel · Long-lived notebook execution and collaboration channel. · `mac/routers/notebook_ws.py`
- [Terminal WS](https://github.com/mbmuniversity2026/mac/blob/master/mac/routers/terminal.py): interactive channel · Shell/terminal session endpoint for interactive compute. · `mac/routers/terminal.py`

### Services

Core domain and coordination logic.

- [Auth & Security](https://github.com/mbmuniversity2026/mac/blob/master/mac/services/auth_service.py): identity/policy · Authentication, scoped keys, token blacklisting, and guardrails. · `mac/services/auth_service.py`
- [Chat & RAG](https://github.com/mbmuniversity2026/mac/blob/master/mac/services/rag_service.py): ai orchestration · Query/chat flows, retrieval assembly, and prompt context routing. · `mac/services/rag_service.py`
- [Notebooks](https://github.com/mbmuniversity2026/mac/blob/master/mac/services/notebook_service.py): execution management · Notebook lifecycle, kernel orchestration, and edit/execute coordination. · `mac/services/notebook_service.py`
- [Nodes & Cluster](https://github.com/mbmuniversity2026/mac/blob/master/mac/services/node_service.py): control plane · Node discovery, cluster state, discovery, and load balancing. · `mac/services/node_service.py`
- [Models & LLM](https://github.com/mbmuniversity2026/mac/blob/master/mac/services/model_service.py): model serving · Model registry, submissions, and inference-node coordination. · `mac/services/model_service.py`
- [Academic Tools](https://github.com/mbmuniversity2026/mac/blob/master/mac/services/attendance_service.py): app domain · Attendance, doubts, copy check, notifications, and activity workflows. · `mac/services/attendance_service.py`
- [Admin & Setup](https://github.com/mbmuniversity2026/mac/blob/master/mac/services/setup_service.py): ops/control · Feature flags, quotas, system setup, usage, hardware, network, and integration. · `mac/services/setup_service.py`

### Data

Persistent and operational infrastructure.

- [PostgreSQL](https://github.com/mbmuniversity2026/mac/blob/master/alembic/versions/20260426_0001_initial_schema.py): primary database · Persistent store for users, notebooks, files, nodes, quotas, flags, and platform state. · `alembic/versions/20260426_0001_initial_schema.py`
- **Redis**: transient state · Rate limiting, blacklists, and short-lived coordination state.
- **Qdrant**: vector store · Embeddings and retrieval index backing RAG features.
- **SearXNG**: search backend · Aggregated search source for explore/search features.

### Workers

Distributed execution and model-serving side.

- [Worker Agent](https://github.com/mbmuniversity2026/mac/blob/master/worker_agent.py): distributed worker · Separate campus-local worker side for compute-heavy execution and node participation. · `worker_agent.py`
- [LLM Nodes](https://github.com/mbmuniversity2026/mac/blob/master/docker-compose.worker.yml): vLLM/Ollama · GPU or model-serving nodes used for chat, notebook assistance, and retrieval-augmented generation. · `docker-compose.worker.yml`

## Connections

- Browser PWA → Nginx: HTTPS · Users access the app through the edge proxy.
- Frontend Modules → Browser PWA: runs in · Feature modules compose the SPA UI.
- Service Worker → Browser PWA: caches · Offline and PWA runtime support.
- Nginx → FastAPI App: proxies API · Forwards REST and WebSocket traffic to the backend.
- FastAPI App → Middleware: applies · Cross-cutting request controls.
- Middleware → API Routers: guards · Requests reach the public API surface after policy checks.
- API Routers → Auth & Security: delegates · Auth, keys, and guardrail endpoints use security services.
- API Routers → Chat & RAG: delegates · Chat/query and retrieval endpoints orchestrate AI flows.
- API Routers → Notebooks: delegates · Notebook CRUD and execution endpoints use notebook services.
- API Routers → Nodes & Cluster: delegates · Node, cluster, discovery, and balancing endpoints use control-plane services.
- API Routers → Models & LLM: delegates · Model and inference management endpoints use model services.
- API Routers → Academic Tools: delegates · Attendance, doubts, copy-check, and notifications endpoints use app services.
- API Routers → Admin & Setup: delegates · Admin, system, quota, usage, setup, and integration endpoints use ops services.
- Notebook WS → Notebooks: feeds · Interactive notebook sessions are coordinated by notebook services.
- Terminal WS → Notebooks: feeds · Terminal sessions share notebook/kernel execution plumbing.
- Auth & Security → PostgreSQL: reads/writes · Users, roles, keys, and security state are persisted.
- Chat & RAG → Qdrant: queries · Retrieval context comes from vector search.
- Chat & RAG → SearXNG: searches · Search/explore flows can aggregate external/internal results.
- Chat & RAG → LLM Nodes: invokes · Requests are sent to model-serving nodes.
- Notebooks → PostgreSQL: reads/writes · Notebook, kernel, and session metadata is persisted.
- Nodes & Cluster → PostgreSQL: reads/writes · Cluster inventory and node state are stored.
- Admin & Setup → Redis: uses · Transient coordination and enforcement state uses Redis.
- Auth & Security → Redis: uses · Rate limits and token blacklist rely on Redis.
- Worker Agent → Nodes & Cluster: reports to · Worker-side agent participates in cluster control.
- Worker Agent → LLM Nodes: hosts · Worker side can provide model-serving or compute capacity.
