# pushkar111/gategaurd-iitgn-databases-cs432 architecture

> Architecture diagram of the GitHub repository pushkar111/gategaurd-iitgn-databases-cs432, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pushkar111/gategaurd-iitgn-databases-cs432
- Repository: https://github.com/pushkar111/gategaurd-iitgn-databases-cs432

## Overview

1. **Repository shape**
   - This repo is not a single app; it is a progression of the same GateGuard system across assignments.
   - The most complete runtime system is in **Assignment 4 Module B**: a full-stack campus gate management platform.
   - Alongside that are two supporting tracks: **Module A** for custom database-engine experiments, and earlier diagram/report/database artifacts.

2. **Top-level runtime boundary**
   - The operational path is: **React frontend in the browser → Express API → PostgreSQL**.
   - In Assignment 4, the database boundary expands from one PostgreSQL instance to **three shard databases** behind a shard router.
   - The frontend never talks to the DB directly; all stateful operations go through the API.

3. **Frontend subsystem**
   - `assignment-*/Module_B/frontend` is a Vite + React app organized by **pages, shared components, layout, hooks, context, and API clients**.
   - `AuthContext`, `useAuth`, and the axios wrapper manage login state, token attachment, and refresh-token recovery.
   - UI behavior is role-aware: guards, admins, and superadmins see different actions, navigation, and pages.

4. **Backend application boundary**
   - `assignment-*/Module_B/backend/src` uses a conventional layered Express structure:
     - **routes** define endpoints,
     - **controllers** translate HTTP to application calls,
     - **services** hold business logic,
     - **models** encapsulate DB access,
     - **middleware** enforces auth, RBAC, validation, auditing, rate limiting, and error handling.
   - `server.js` and `app.js` are the bootstrap entry points; `config/` holds DB, env, and CORS setup.

5. **Core domain flow**
   - The primary business objects are **members, vehicles, gates, person visits, vehicle visits, gate occupancy, roles, and users**.
   - Visit entry/exit flows are the heart of the system: they update visit records, affect gate occupancy, and produce audit events.
   - Dashboard endpoints aggregate these operational tables into recent activity and summary metrics.

6. **Security and access-control boundary**
   - Authentication is JWT-based with **access + refresh tokens**.
   - Authorization is enforced by **RBAC middleware**, with distinct permissions for Guard, Admin, and SuperAdmin.
   - Additional protections include **rate limiting**, account lockout, first-login password change, OTP-based password reset, refresh-token revocation, and token blacklist checks.
   - Email is used for reset and account-notification flows.

7. **Audit and traceability**
   - Writes are observable in two places: a persistent **audit table in PostgreSQL** and an **append-only file log**.
   - Audit middleware captures who changed what and when, which is important for admin actions, visit changes, and user-management events.
   - This makes the system operationally traceable rather than just CRUD-oriented.

8. **Database and performance layer**
   - SQL assets in `backend/sql` define auth tables, audit tables, direct-write guards, indexes, and seed data.
   - The repo includes explicit performance tooling: health checks, explain-plan generation, large-data seeding, and index strategy validation.
   - The design emphasizes indexed lookups for members, vehicles, auth records, and visit timelines.

9. **Assignment 3 Module A: custom DB engine**
   - Separate from the web app, `assignment-3/Module_A/database` implements a miniature database engine in Python.
   - Its main pieces are **B+ tree storage, write-ahead logging, transaction management, recovery, and consistency checking**.
   - This track demonstrates ACID-style behavior in memory/disk logs, independent of PostgreSQL.

10. **Assignment 3 Module B: concurrency validation**
   - `assignment-3/Module_B/stress_tests` validates the backend under race and failure scenarios.
   - The key architectural concern here is concurrency safety in visit creation, especially preventing duplicate or inconsistent entries.
   - The stress suite exercises load, race conditions, and failure handling against the live API and DB.

11. **Assignment 4 sharding architecture**
   - Assignment 4 moves the data layer to **three PostgreSQL shard containers** orchestrated by Docker Compose.
   - Shard placement is deterministic: **`id % 3`**.
   - A shard router in both Python and JavaScript maps member and visit operations to the correct shard, while global reads use scatter-gather aggregation.
   - `personVisit.service.js` is the main shard-aware backend path and preserves locking behavior during writes.

12. **What to draw in an architecture diagram**
   - Show three major runtime tiers: **frontend**, **API/backend**, and **database layer**.
   - Inside the backend, show cross-cutting middleware for **auth/RBAC/validation/audit/error handling** around the service layer.
   - For Assignment 4, show a **shard router** between services and multiple PostgreSQL nodes.
   - Separately annotate the Python DB-engine track as an experimental subsystem with WAL/transactions/recovery, since it is architecturally distinct from the production web stack.

Main entry points: [`assignment-4/Module_A/database`](https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_A/database) (DB Engine), [`assignment-4/Module_B/backend/src/services`](https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/backend/src/services) (Services), [`assignment-4/Module_B/frontend`](https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/frontend) (Frontend), [`assignment-4/Module_B/backend/sql`](https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/backend/sql) (SQL Assets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web_platform["Production Web Stack"]
  node_frontend_app["Frontend<br/>React/Vite UI"]
  node_frontend_auth["Auth UI<br/>context/hooks/api<br/>[AuthContext.jsx]"]
  node_frontend_pages["Pages<br/>views"]
  node_frontend_components["Shared UI<br/>components"]
  node_api_bootstrap["API Bootstrap<br/>Express entrypoints<br/>[app.js]"]
  node_api_routes["Routes<br/>HTTP endpoints"]
  node_api_controllers["Controllers<br/>HTTP adapters"]
  node_api_services["Services<br/>business logic"]
  node_api_middleware["Middleware<br/>cross-cutting"]
  node_api_models[("Models<br/>data access")]
  node_shard_router_js["Shard Router<br/>routing logic<br/>[shardRouter.js]"]
  node_shard_db_1[("Shard 1<br/>PostgreSQL shard")]
  node_shard_db_2[("Shard 2<br/>PostgreSQL shard")]
  node_shard_db_3[("Shard 3<br/>PostgreSQL shard")]
  node_audit_log["Audit Log<br/>append-only trace"]
end

subgraph group_db_engine_lab["DB Engine Lab"]
  node_db_engine_core["DB Engine<br/>Python lab"]
  node_bplustree["B+ Tree<br/>index/storage<br/>[bplustree.py]"]
  node_wal["WAL<br/>logging<br/>[wal.py]"]
  node_transactions["Transactions<br/>ACID control<br/>[transaction.py]"]
  node_recovery["Recovery<br/>[recovery.py]"]
  node_shard_router_py["Shard Router<br/>Python routing<br/>[shard_router.py]"]
end

subgraph group_verification["Validation & Ops"]
  node_stress_tests["Stress Tests<br/>validation suite"]
  node_sql_assets["SQL Assets<br/>schema/index scripts"]
end

node_frontend_app -->|"state"| node_frontend_auth
node_frontend_app -->|"renders"| node_frontend_pages
node_frontend_app -->|"uses"| node_frontend_components
node_frontend_app -->|"api calls"| node_api_bootstrap
node_api_bootstrap -->|"mounts"| node_api_routes
node_api_routes -->|"dispatches"| node_api_controllers
node_api_controllers -->|"calls"| node_api_services
node_api_services -.->|"guarded by"| node_api_middleware
node_api_services -->|"persists via"| node_api_models
node_api_services -->|"sharded reads/writes"| node_shard_router_js
node_shard_router_js -->|"targets"| node_shard_db_1
node_shard_router_js -->|"targets"| node_shard_db_2
node_shard_router_js -->|"targets"| node_shard_db_3
node_api_services -->|"records"| node_audit_log
node_db_engine_core -->|"stores"| node_bplustree
node_db_engine_core -->|"logs"| node_wal
node_db_engine_core -->|"controls"| node_transactions
node_db_engine_core -->|"restores"| node_recovery
node_db_engine_core -->|"routes"| node_shard_router_py
node_stress_tests -->|"exercises"| node_api_bootstrap
node_sql_assets -->|"supports"| node_api_models
node_sql_assets -.->|"applies to"| node_shard_db_1
node_sql_assets -.->|"applies to"| node_shard_db_2
node_sql_assets -.->|"applies to"| node_shard_db_3

click node_frontend_app "https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/frontend"
click node_frontend_auth "https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/blob/main/assignment-4/Module_B/frontend/src/context/AuthContext.jsx"
click node_frontend_pages "https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/frontend/src/pages"
click node_frontend_components "https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/frontend/src/components"
click node_api_bootstrap "https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/blob/main/assignment-4/Module_B/backend/src/app.js"
click node_api_routes "https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/backend/src/routes"
click node_api_controllers "https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/backend/src/controllers"
click node_api_services "https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/backend/src/services"
click node_api_middleware "https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/backend/src/middleware"
click node_api_models "https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/backend/src/models"
click node_shard_router_js "https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/blob/main/assignment-4/Module_B/backend/src/utils/shardRouter.js"
click node_shard_db_1 "https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/backend"
click node_shard_db_2 "https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/backend"
click node_shard_db_3 "https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/backend"
click node_audit_log "https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/backend/logs"
click node_db_engine_core "https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_A/database"
click node_bplustree "https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/blob/main/assignment-4/Module_A/database/bplustree.py"
click node_wal "https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/blob/main/assignment-4/Module_A/database/wal.py"
click node_transactions "https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/blob/main/assignment-4/Module_A/database/transaction.py"
click node_recovery "https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/blob/main/assignment-4/Module_A/database/recovery.py"
click node_shard_router_py "https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/blob/main/assignment-4/Module_A/database/shard_router.py"
click node_stress_tests "https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/stress_tests"
click node_sql_assets "https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/backend/sql"

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_frontend_app,node_frontend_auth,node_frontend_pages,node_frontend_components,node_api_bootstrap,node_api_routes,node_api_controllers,node_api_services,node_api_middleware,node_api_models,node_shard_router_js,node_shard_db_1,node_shard_db_2,node_shard_db_3,node_audit_log toneBlue
class node_db_engine_core,node_bplustree,node_wal,node_transactions,node_recovery,node_shard_router_py toneAmber
class node_stress_tests,node_sql_assets toneMint
```

## Components

### Production Web Stack

Assignment 4 full-stack GateGuard runtime

- [Frontend](https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/frontend): React/Vite UI · Browser app with role-aware pages, shared components, and auth state · `assignment-4/Module_B/frontend`
- [Auth UI](https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/blob/main/assignment-4/Module_B/frontend/src/context/AuthContext.jsx): context/hooks/api · Login state, token attachment, refresh recovery, and protected navigation · `assignment-4/Module_B/frontend/src/context/AuthContext.jsx`
- [Pages](https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/frontend/src/pages): views · Dashboards, visits, members, vehicles, admin screens, and role-specific actions · `assignment-4/Module_B/frontend/src/pages`
- [Shared UI](https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/frontend/src/components): components · Layouts, action center, tables, dialogs, badges, and reusable controls · `assignment-4/Module_B/frontend/src/components`
- [API Bootstrap](https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/blob/main/assignment-4/Module_B/backend/src/app.js): Express entrypoints · Server and app wiring, CORS, env, and database configuration · `assignment-4/Module_B/backend/src/app.js`
- [Routes](https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/backend/src/routes): HTTP endpoints · Endpoint layer for auth, members, vehicles, visits, gates, dashboard, and admin audit · `assignment-4/Module_B/backend/src/routes`
- [Controllers](https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/backend/src/controllers): HTTP adapters · Translate requests into application calls and response shaping · `assignment-4/Module_B/backend/src/controllers`
- [Services](https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/backend/src/services): business logic · Core domain logic for auth, dashboard, gates, members, users, and visits · `assignment-4/Module_B/backend/src/services`
- [Middleware](https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/backend/src/middleware): cross-cutting · JWT auth, RBAC, validation, audit capture, rate limiting, and errors · `assignment-4/Module_B/backend/src/middleware`
- [Models](https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/backend/src/models): data access · Persistence layer for users, roles, members, vehicles, visits, occupancy, and audit · `assignment-4/Module_B/backend/src/models`
- [Shard Router](https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/blob/main/assignment-4/Module_B/backend/src/utils/shardRouter.js): routing logic · Deterministic shard mapping and scatter-gather aggregation for reads · `assignment-4/Module_B/backend/src/utils/shardRouter.js`
- [Shard 1](https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/backend): PostgreSQL shard · One of three sharded PostgreSQL nodes · `assignment-4/Module_B/backend`
- [Shard 2](https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/backend): PostgreSQL shard · One of three sharded PostgreSQL nodes · `assignment-4/Module_B/backend`
- [Shard 3](https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/backend): PostgreSQL shard · One of three sharded PostgreSQL nodes · `assignment-4/Module_B/backend`
- [Audit Log](https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/backend/logs): append-only trace · Persistent audit table plus file logging for traceability · `assignment-4/Module_B/backend/logs`

### DB Engine Lab

Python storage and sharding experiments

- [DB Engine](https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_A/database): Python lab · Mini database engine used in the assignment-4 Module_A track · `assignment-4/Module_A/database`
- [B+ Tree](https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/blob/main/assignment-4/Module_A/database/bplustree.py): index/storage · Primary in-memory/disk-oriented key structure · `assignment-4/Module_A/database/bplustree.py`
- [WAL](https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/blob/main/assignment-4/Module_A/database/wal.py): logging · Write-ahead logging for durable mutation replay · `assignment-4/Module_A/database/wal.py`
- [Transactions](https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/blob/main/assignment-4/Module_A/database/transaction.py): ACID control · Transaction boundaries and consistency coordination · `assignment-4/Module_A/database/transaction.py`
- [Recovery](https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/blob/main/assignment-4/Module_A/database/recovery.py): crash recovery · Rebuilds state from log and stored data · `assignment-4/Module_A/database/recovery.py`
- [Shard Router](https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/blob/main/assignment-4/Module_A/database/shard_router.py): Python routing · Python-side shard mapping used in the sharding experiment · `assignment-4/Module_A/database/shard_router.py`

### Validation & Ops

Stress tests, SQL assets, and operational tooling

- [Stress Tests](https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/stress_tests): validation suite · Race, failure, and load testing against the live API and DB · `assignment-4/Module_B/stress_tests`
- [SQL Assets](https://github.com/pushkar111/gategaurd-iitgn-databases-cs432/tree/main/assignment-4/Module_B/backend/sql): schema/index scripts · Auth tables, audit tables, direct-write guards, explain plans, and indexes · `assignment-4/Module_B/backend/sql`

## Connections

- Frontend → Auth UI: state · Auth context and hooks manage session state and token recovery
- Frontend → Pages: renders · Routes to role-aware pages and admin screens
- Frontend → Shared UI: uses · Shared UI and action-center components
- Frontend → API Bootstrap: api calls · Frontend talks only through the HTTP API
- API Bootstrap → Routes: mounts · Registers route modules on the Express app
- Routes → Controllers: dispatches · Routes hand requests to controllers
- Controllers → Services: calls · Controllers invoke application services
- Services → Middleware: guarded by · Auth, RBAC, validation, audit, rate limiting, and error handling
- Services → Models: persists via · Services use models for database access
- Services → Shard Router: sharded reads/writes · Shard-aware visit and member operations route through the router
- Shard Router → Shard 1: targets · Deterministic shard placement based on identifier modulo
- Shard Router → Shard 2: targets · Deterministic shard placement based on identifier modulo
- Shard Router → Shard 3: targets · Deterministic shard placement based on identifier modulo
- Services → Audit Log: records · Administrative and visit changes are traced in persistent audit logs
- DB Engine → B+ Tree: stores · Core key/value and table storage structure
- DB Engine → WAL: logs · Durable mutation logging
- DB Engine → Transactions: controls · Transaction lifecycle and atomicity
- DB Engine → Recovery: restores · Crash recovery and replay
- DB Engine → Shard Router: routes · Python sharding experiment uses router abstraction
- Stress Tests → API Bootstrap: exercises · Race and failure tests hit the running backend
- SQL Assets → Models: supports · Schema, indexes, and direct-write guards back the model layer
- SQL Assets → Shard 1: applies to · Shard schema and performance scripts
- SQL Assets → Shard 2: applies to · Shard schema and performance scripts
- SQL Assets → Shard 3: applies to · Shard schema and performance scripts
