How mbmuniversity2026/mac works
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: routers API Routers · rag_service.py Chat & RAG · notebook_service.py Notebooks · auth_service.py Auth & Security
Components 22
Client
Browser-facing UI and offline assets.
- Browser PWA · Static campus browser UI with offline support and feature pages.
frontend/index.html - Frontend Modules · Chat, notebooks, doubts, attendance, files, admin, settings, shell, notifications.
frontend/js - Service Worker · Offline caching and app-shell support for the frontend.
frontend/sw.js
Edge
Deployment and request entrypoint.
- Nginx · Serves the static frontend and proxies API/WebSocket traffic.
nginx/nginx.conf
Backend
FastAPI application surface and orchestration.
- FastAPI App · Main application entrypoint and request lifecycle.
mac/main.py - Middleware · JWT auth, feature gating, and rate limiting before routes.
mac/middleware - API Routers · Public endpoints for auth, chat, notebooks, RAG, files, nodes, admin, search, and more.
mac/routers - Notebook WS · Long-lived notebook execution and collaboration channel.
mac/routers/notebook_ws.py - Terminal WS · Shell/terminal session endpoint for interactive compute.
mac/routers/terminal.py
Services
Core domain and coordination logic.
- Auth & Security · Authentication, scoped keys, token blacklisting, and guardrails.
mac/services/auth_service.py - Chat & RAG · Query/chat flows, retrieval assembly, and prompt context routing.
mac/services/rag_service.py - Notebooks · Notebook lifecycle, kernel orchestration, and edit/execute coordination.
mac/services/notebook_service.py - Nodes & Cluster · Node discovery, cluster state, discovery, and load balancing.
mac/services/node_service.py - Models & LLM · Model registry, submissions, and inference-node coordination.
mac/services/model_service.py - Academic Tools · Attendance, doubts, copy check, notifications, and activity workflows.
mac/services/attendance_service.py - Admin & Setup · Feature flags, quotas, system setup, usage, hardware, network, and integration.
mac/services/setup_service.py
Data
Persistent and operational infrastructure.
- PostgreSQL · Persistent store for users, notebooks, files, nodes, quotas, flags, and platform state.
alembic/versions/20260426_0001_initial_schema.py - Redis · Rate limiting, blacklists, and short-lived coordination state.
- Qdrant · Embeddings and retrieval index backing RAG features.
- SearXNG · Aggregated search source for explore/search features.
Workers
Distributed execution and model-serving side.
- Worker Agent · Separate campus-local worker side for compute-heavy execution and node participation.
worker_agent.py - LLM Nodes · GPU or model-serving nodes used for chat, notebook assistance, and retrieval-augmented generation.
docker-compose.worker.yml
Connections 25
- 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.