# sadman7202/diu-hall-ai-assistant architecture

> Architecture diagram of the GitHub repository sadman7202/diu-hall-ai-assistant, 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/sadman7202/diu-hall-ai-assistant
- Repository: https://github.com/sadman7202/diu-hall-ai-assistant

## Overview

1. **Overall shape**
   - This is a full-stack hall-operations platform with a **React + Vite SPA** on the front end and a **FastAPI** backend on the server side.
   - The backend is a **modular monolith**: one API application, but split into domain-focused modules for auth, gate passes, notices, complaints, notifications, chat, and hall rules.

2. **Frontend boundary**
   - The frontend is a single-page app under `frontend/src`, with route-level pages for **login/register**, **dashboard**, **profile**, **gate pass**, **gate security**, **notice board**, **complaints**, **chatbot**, and **admin rules**.
   - `NotificationBell.jsx` is a shared UI component, indicating notifications are a cross-cutting feature surfaced throughout the app.
   - The frontend talks to the backend via REST APIs and uses JWT-based authenticated requests.

3. **Backend application entry and structure**
   - `backend/app/main.py` is the FastAPI entry point.
   - `backend/app/core` contains environment/config handling, dependency wiring, and security helpers.
   - `backend/app/db` contains SQLAlchemy session/base setup and a seeding script for hall rules.
   - `backend/app/models` defines the persisted entities, while `backend/app/services` holds higher-level workflows such as notifications and RAG logic.

4. **Primary data store**
   - The main relational store is **PostgreSQL**, accessed through **SQLAlchemy**.
   - Core tables map directly to the domain: `users`, `gate_passes`, `notices`, `complaints`, `notifications`, `hall_rules`, `chat_sessions`, and `chat_messages`.
   - The project currently relies on `Base.metadata.create_all(...)` rather than a migration framework, so schema changes can require manual database updates.

5. **Identity, roles, and access control**
   - Authentication is JWT-based, with role separation for **student**, **admin**, and **gate_security**.
   - Access boundaries are enforced by role: students manage their own profile, complaints, and gate passes; admins manage approvals, notices, rules, and notifications; gate security can only verify and mark passes as used.
   - Password reset is handled through tokenized email flow, and signatures are stored as user profile data for approval workflows.

6. **Gate-pass workflow is the main transactional flow**
   - Students submit a gate-pass request into the backend.
   - Admins approve or reject it; approval triggers several downstream actions:
     - generate a **verification ID**
     - generate a **QR code**
     - generate a **PDF gate pass**
     - store generated artifacts under backend upload directories
   - The gate-security portal does not “consume” the QR directly; it first verifies the pass, then a separate confirm action marks it as used. That distinction is an important business rule and a key diagram boundary.

7. **File and artifact storage**
   - This repo stores operational files on disk inside the backend:
     - uploaded signatures under `backend/uploads/signatures`
     - generated PDFs under `backend/uploads/gate_pass_pdfs`
     - generated QR images under `backend/uploads/gate_pass_qr_codes`
   - Static signature assets used in PDFs live under `backend/assets/signatures`.
   - Because these are file-system artifacts, the architecture depends on writable local storage, not just the database.

8. **Notifications as a cross-cutting service**
   - `backend/app/services/notifications.py` centralizes in-app notification creation and read-state updates.
   - Notifications are tied to domain events such as gate-pass approval/rejection, complaint status updates, notices, and hall-rule changes.
   - Email notification support exists as an optional side channel via SMTP, but in-app notifications are part of the core system.

9. **Notice board and complaints are separate admin-student workflows**
   - Notices are admin-authored and publicly readable, with optional deadlines and notification fan-out.
   - Complaints are student-submitted, then reviewed and updated by admins.
   - These are not deeply coupled to gate passes, but both feed the notification system and are part of the hall-management domain.

10. **AI assistant / RAG subsystem**
   - The chatbot is a separate retrieval pipeline under `backend/app/services/rag`.
   - Hall rules are the source data, seeded from `backend/app/data/processed/chunks_updated.json` into PostgreSQL and indexed into **ChromaDB**.
   - Query handling has two paths:
     - exact rule-number lookup from the relational store
     - semantic retrieval through **Sentence Transformers** embeddings and ChromaDB
   - This means the AI layer is not a general LLM chatbot; it is a retrieval-based assistant grounded in hall-rule data.

11. **Vector storage is a distinct subsystem**
   - The vector database is persisted locally under `backend/app/data/vectordb`.
   - It is used only for semantic rule lookup, so it is a support index rather than the system of record.
   - The admin can rebuild the index, which implies a maintenance boundary between the authoritative hall-rule table and the derived vector store.

12. **Runtime and deployment boundary**
   - The repo is designed to run either manually or through **Docker Compose**.
   - `docker-compose.yml` coordinates at least three services conceptually: backend, frontend, and PostgreSQL.
   - The backend serves API responses and static file paths; the frontend is a separate dev/build artifact served by Vite in development.

13. **Key architectural flow to diagram**
   - A good diagram should show:
     - browser users entering the React SPA
     - SPA calling FastAPI with JWT
     - FastAPI reading/writing PostgreSQL
     - FastAPI writing PDFs, signatures, and QR codes to local storage
     - FastAPI indexing/querying ChromaDB for chatbot retrieval
     - optional SMTP for email notifications and password reset

14. **What makes this repo distinctive**
   - The project is not just CRUD: its most important complexity comes from the **gate-pass approval + QR verification lifecycle** and the **hall-rule RAG assistant**.
   - Those two flows connect multiple subsystems: database, file storage, notifications, and role-based access control, with the chatbot also depending on a derived vector index.

Main entry points: [`backend/app/main.py`](https://github.com/sadman7202/diu-hall-ai-assistant/blob/main/backend/app/main.py) (FastAPI App), [`frontend/src/App.jsx`](https://github.com/sadman7202/diu-hall-ai-assistant/blob/main/frontend/src/App.jsx) (React SPA), [`backend/app/services/rag`](https://github.com/sadman7202/diu-hall-ai-assistant/tree/main/backend/app/services/rag) (Chat RAG), [`backend/app/models/gate_pass.py`](https://github.com/sadman7202/diu-hall-ai-assistant/blob/main/backend/app/models/gate_pass.py) (Gate Passes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend SPA"]
  node_spa["React SPA<br/>frontend app<br/>[App.jsx]"]
  node_pages["App Pages<br/>route pages"]
  node_notif_ui(("Notif Bell<br/>shared ui"))
end

subgraph group_backend["Backend API"]
  node_api["FastAPI App<br/>api entrypoint<br/>[main.py]"]
  node_core["Core Config<br/>auth/config"]
  node_gate_pass["Gate Passes<br/>workflow module<br/>[gate_pass.py]"]
  node_notifications["Notifications<br/>[notifications.py]"]
  node_chat_rag["Chat RAG<br/>retrieval assistant"]
  node_authz["Users & Roles<br/>identity layer<br/>[user.py]"]
  node_notice_complaint["Notices & Complaints<br/>admin workflows<br/>[notice.py]"]
  node_hall_rules["Hall Rules<br/>domain data<br/>[hall_rule.py]"]
end

subgraph group_storage["Local Data"]
  node_db[("PostgreSQL<br/>relational store<br/>[session.py]")]
  node_uploads[("Upload Store<br/>file storage")]
  node_assets["Signature Assets<br/>static files"]
  node_vectordb[("ChromaDB<br/>vector store")]
  node_seed_data["Rule Seed Data<br/>seed corpus"]
end

node_browser(("Users<br/>client"))

node_browser -->|"use"| node_spa
node_spa -->|"routes"| node_pages
node_spa -->|"show"| node_notif_ui
node_spa -->|"REST + JWT"| node_api
node_api -->|"configures"| node_core
node_api -->|"auth/roles"| node_authz
node_api -->|"manages"| node_gate_pass
node_api -->|"manages"| node_notice_complaint
node_api -->|"emits"| node_notifications
node_api -->|"serves"| node_chat_rag
node_api -->|"reads/writes"| node_hall_rules
node_api -->|"persist"| node_db
node_gate_pass -->|"write artifacts"| node_uploads
node_gate_pass -->|"render PDFs"| node_assets
node_chat_rag -->|"exact lookup"| node_db
node_chat_rag -->|"semantic search"| node_vectordb
node_chat_rag -->|"index source"| node_seed_data
node_seed_data -->|"seed"| node_db
node_seed_data -->|"build index"| node_vectordb

click node_spa "https://github.com/sadman7202/diu-hall-ai-assistant/blob/main/frontend/src/App.jsx"
click node_pages "https://github.com/sadman7202/diu-hall-ai-assistant/tree/main/frontend/src/pages"
click node_notif_ui "https://github.com/sadman7202/diu-hall-ai-assistant/blob/main/frontend/src/components/NotificationBell.jsx"
click node_api "https://github.com/sadman7202/diu-hall-ai-assistant/blob/main/backend/app/main.py"
click node_core "https://github.com/sadman7202/diu-hall-ai-assistant/tree/main/backend/app/core"
click node_gate_pass "https://github.com/sadman7202/diu-hall-ai-assistant/blob/main/backend/app/models/gate_pass.py"
click node_notifications "https://github.com/sadman7202/diu-hall-ai-assistant/blob/main/backend/app/services/notifications.py"
click node_chat_rag "https://github.com/sadman7202/diu-hall-ai-assistant/tree/main/backend/app/services/rag"
click node_authz "https://github.com/sadman7202/diu-hall-ai-assistant/blob/main/backend/app/models/user.py"
click node_notice_complaint "https://github.com/sadman7202/diu-hall-ai-assistant/blob/main/backend/app/models/notice.py"
click node_hall_rules "https://github.com/sadman7202/diu-hall-ai-assistant/blob/main/backend/app/models/hall_rule.py"
click node_db "https://github.com/sadman7202/diu-hall-ai-assistant/blob/main/backend/app/db/session.py"
click node_uploads "https://github.com/sadman7202/diu-hall-ai-assistant/tree/main/backend/uploads"
click node_assets "https://github.com/sadman7202/diu-hall-ai-assistant/tree/main/backend/assets/signatures"
click node_vectordb "https://github.com/sadman7202/diu-hall-ai-assistant/tree/main/backend/app/data/vectordb"
click node_seed_data "https://github.com/sadman7202/diu-hall-ai-assistant/blob/main/backend/app/data/processed/chunks_updated.json"

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_spa,node_pages,node_notif_ui toneBlue
class node_api,node_core,node_gate_pass,node_notifications,node_chat_rag,node_authz,node_notice_complaint,node_hall_rules toneAmber
class node_db,node_uploads,node_assets,node_vectordb,node_seed_data toneMint
class node_browser toneNeutral
```

## Components

### Frontend SPA

React + Vite client and route-level pages.

- [React SPA](https://github.com/sadman7202/diu-hall-ai-assistant/blob/main/frontend/src/App.jsx): frontend app · Single-page frontend shell and route entrypoint. · `frontend/src/App.jsx`
- [App Pages](https://github.com/sadman7202/diu-hall-ai-assistant/tree/main/frontend/src/pages): route pages · Login, dashboard, profile, gate pass, security, notices, complaints, chatbot, and admin rules pages. · `frontend/src/pages`
- [Notif Bell](https://github.com/sadman7202/diu-hall-ai-assistant/blob/main/frontend/src/components/NotificationBell.jsx): shared ui · Cross-cutting notification indicator shown throughout the frontend. · `frontend/src/components/NotificationBell.jsx`

### Backend API

FastAPI app, domain modules, and shared services.

- [FastAPI App](https://github.com/sadman7202/diu-hall-ai-assistant/blob/main/backend/app/main.py): api entrypoint · Backend application entrypoint and HTTP surface. · `backend/app/main.py`
- [Core Config](https://github.com/sadman7202/diu-hall-ai-assistant/tree/main/backend/app/core): auth/config · Environment config, dependency wiring, and security helpers. · `backend/app/core`
- [Gate Passes](https://github.com/sadman7202/diu-hall-ai-assistant/blob/main/backend/app/models/gate_pass.py): workflow module · Student requests, admin approval, verification ID, QR, PDF generation, and security confirmation. · `backend/app/models/gate_pass.py`
- [Notifications](https://github.com/sadman7202/diu-hall-ai-assistant/blob/main/backend/app/services/notifications.py): service · In-app notification creation, fan-out, and read-state updates. · `backend/app/services/notifications.py`
- [Chat RAG](https://github.com/sadman7202/diu-hall-ai-assistant/tree/main/backend/app/services/rag): retrieval assistant · Hall-rule chatbot with exact lookup and semantic retrieval paths. · `backend/app/services/rag`
- [Users & Roles](https://github.com/sadman7202/diu-hall-ai-assistant/blob/main/backend/app/models/user.py): identity layer · JWT auth and role boundaries for students, admins, and gate security. · `backend/app/models/user.py`
- [Notices & Complaints](https://github.com/sadman7202/diu-hall-ai-assistant/blob/main/backend/app/models/notice.py): admin workflows · Admin-authored notices and student-submitted complaints with review flows. · `backend/app/models/notice.py`
- [Hall Rules](https://github.com/sadman7202/diu-hall-ai-assistant/blob/main/backend/app/models/hall_rule.py): domain data · Authoritative hall-rule records used by admin tools and the chatbot. · `backend/app/models/hall_rule.py`

### Local Data

Relational, vector, and file-system artifacts used by the app.

- [PostgreSQL](https://github.com/sadman7202/diu-hall-ai-assistant/blob/main/backend/app/db/session.py): relational store · System of record for users, passes, notices, complaints, notifications, chat, and rules. · `backend/app/db/session.py`
- [Upload Store](https://github.com/sadman7202/diu-hall-ai-assistant/tree/main/backend/uploads): file storage · Local PDFs, signatures, and QR artifacts written by the backend. · `backend/uploads`
- [Signature Assets](https://github.com/sadman7202/diu-hall-ai-assistant/tree/main/backend/assets/signatures): static files · Static signature images used in generated gate-pass PDFs. · `backend/assets/signatures`
- [ChromaDB](https://github.com/sadman7202/diu-hall-ai-assistant/tree/main/backend/app/data/vectordb): vector store · Derived semantic index for hall-rule retrieval. · `backend/app/data/vectordb`
- [Rule Seed Data](https://github.com/sadman7202/diu-hall-ai-assistant/blob/main/backend/app/data/processed/chunks_updated.json): seed corpus · Processed hall-rule chunks used to populate the database and vector index. · `backend/app/data/processed/chunks_updated.json`

### Other components

- **Users**: client · Students, admins, and gate security staff using the web app.

## Connections

- Users → React SPA: use · Users interact with the React frontend.
- React SPA → App Pages: routes · The SPA renders the major application pages.
- React SPA → Notif Bell: show · Notification state is surfaced through a shared bell component.
- React SPA → FastAPI App: REST + JWT · Frontend calls backend APIs with authenticated requests.
- FastAPI App → Core Config: configures · FastAPI wires settings, dependencies, and security helpers.
- FastAPI App → Users & Roles: auth/roles · Authentication and role-based access control gate backend actions.
- FastAPI App → Gate Passes: manages · Gate-pass submission, approval, verification, and usage confirmation.
- FastAPI App → Notices & Complaints: manages · Notices and complaints are handled as separate admin-student workflows.
- FastAPI App → Notifications: emits · Domain events create and update in-app notifications.
- FastAPI App → Chat RAG: serves · Chat requests are answered through the hall-rule retrieval pipeline.
- FastAPI App → Hall Rules: reads/writes · Hall rules are maintained in the relational system of record.
- FastAPI App → PostgreSQL: persist · Core domain data is stored in PostgreSQL via SQLAlchemy.
- Gate Passes → Upload Store: write artifacts · Approved passes produce PDFs and QR images on local storage.
- Gate Passes → Signature Assets: render PDFs · Static signature assets are embedded into generated documents.
- Chat RAG → PostgreSQL: exact lookup · Rule-number queries are answered from the database.
- Chat RAG → ChromaDB: semantic search · Embedding-based retrieval queries the local ChromaDB index.
- Chat RAG → Rule Seed Data: index source · Seed corpus feeds the derived retrieval index and rule records.
- Rule Seed Data → PostgreSQL: seed · Processed rule chunks populate hall-rule rows.
- Rule Seed Data → ChromaDB: build index · The same corpus is embedded into the vector store.
