How pushkar111/gategaurd-iitgn-databases-cs432 works
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: database DB Engine · services Services · frontend Frontend · sql SQL Assets
Components 23
Production Web Stack
Assignment 4 full-stack GateGuard runtime
- Frontend · Browser app with role-aware pages, shared components, and auth state
assignment-4/Module_B/frontend - Auth UI · Login state, token attachment, refresh recovery, and protected navigation
assignment-4/Module_B/frontend/src/context/AuthContext.jsx - Pages · Dashboards, visits, members, vehicles, admin screens, and role-specific actions
assignment-4/Module_B/frontend/src/pages - Shared UI · Layouts, action center, tables, dialogs, badges, and reusable controls
assignment-4/Module_B/frontend/src/components - API Bootstrap · Server and app wiring, CORS, env, and database configuration
assignment-4/Module_B/backend/src/app.js - Routes · Endpoint layer for auth, members, vehicles, visits, gates, dashboard, and admin audit
assignment-4/Module_B/backend/src/routes - Controllers · Translate requests into application calls and response shaping
assignment-4/Module_B/backend/src/controllers - Services · Core domain logic for auth, dashboard, gates, members, users, and visits
assignment-4/Module_B/backend/src/services - Middleware · JWT auth, RBAC, validation, audit capture, rate limiting, and errors
assignment-4/Module_B/backend/src/middleware - Models · Persistence layer for users, roles, members, vehicles, visits, occupancy, and audit
assignment-4/Module_B/backend/src/models - Shard Router · Deterministic shard mapping and scatter-gather aggregation for reads
assignment-4/Module_B/backend/src/utils/shardRouter.js - Shard 1 · One of three sharded PostgreSQL nodes
assignment-4/Module_B/backend - Shard 2 · One of three sharded PostgreSQL nodes
assignment-4/Module_B/backend - Shard 3 · One of three sharded PostgreSQL nodes
assignment-4/Module_B/backend - Audit Log · Persistent audit table plus file logging for traceability
assignment-4/Module_B/backend/logs
DB Engine Lab
Python storage and sharding experiments
- DB Engine · Mini database engine used in the assignment-4 Module_A track
assignment-4/Module_A/database - B+ Tree · Primary in-memory/disk-oriented key structure
assignment-4/Module_A/database/bplustree.py - WAL · Write-ahead logging for durable mutation replay
assignment-4/Module_A/database/wal.py - Transactions · Transaction boundaries and consistency coordination
assignment-4/Module_A/database/transaction.py - Recovery · Rebuilds state from log and stored data
assignment-4/Module_A/database/recovery.py - Shard Router · 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 · Race, failure, and load testing against the live API and DB
assignment-4/Module_B/stress_tests - SQL Assets · Auth tables, audit tables, direct-write guards, explain plans, and indexes
assignment-4/Module_B/backend/sql
Connections 24
- 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