How sadman7202/diu-hall-ai-assistant works
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: main.py FastAPI App · App.jsx React SPA · rag Chat RAG · gate_pass.py Gate Passes
Components 17
Frontend SPA
React + Vite client and route-level pages.
- React SPA · Single-page frontend shell and route entrypoint.
frontend/src/App.jsx - App Pages · Login, dashboard, profile, gate pass, security, notices, complaints, chatbot, and admin rules pages.
frontend/src/pages - Notif Bell · Cross-cutting notification indicator shown throughout the frontend.
frontend/src/components/NotificationBell.jsx
Backend API
FastAPI app, domain modules, and shared services.
- FastAPI App · Backend application entrypoint and HTTP surface.
backend/app/main.py - Core Config · Environment config, dependency wiring, and security helpers.
backend/app/core - Gate Passes · Student requests, admin approval, verification ID, QR, PDF generation, and security confirmation.
backend/app/models/gate_pass.py - Notifications · In-app notification creation, fan-out, and read-state updates.
backend/app/services/notifications.py - Chat RAG · Hall-rule chatbot with exact lookup and semantic retrieval paths.
backend/app/services/rag - Users & Roles · JWT auth and role boundaries for students, admins, and gate security.
backend/app/models/user.py - Notices & Complaints · Admin-authored notices and student-submitted complaints with review flows.
backend/app/models/notice.py - Hall Rules · 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 · System of record for users, passes, notices, complaints, notifications, chat, and rules.
backend/app/db/session.py - Upload Store · Local PDFs, signatures, and QR artifacts written by the backend.
backend/uploads - Signature Assets · Static signature images used in generated gate-pass PDFs.
backend/assets/signatures - ChromaDB · Derived semantic index for hall-rule retrieval.
backend/app/data/vectordb - Rule Seed Data · Processed hall-rule chunks used to populate the database and vector index.
backend/app/data/processed/chunks_updated.json
Other components
- Users · Students, admins, and gate security staff using the web app.
Connections 19
- 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.