Project Context

2. admin/ (Administrative Portal)

• Role: The back-office system for hall administrators (Provost, Section Officers, Dining Managers, etc.) to manage students, approve applications, resolve asset damage, and oversee finances.
• Framework: Next.js (App Router), React 19, TypeScript.
• Styling & UI:
  • Tailwind CSS v4.
  • Radix UI Primitive Focused: Relies heavily on @radix-ui/react-* components for building highly functional and robust data-management interfaces, alongside lucide-react forms.
  • Less visual flair than the student web app, but highly functional.
• Run/Port: Custom dev starts on Port 4001.

3. backend/ (Main API Server)

The absolute core of the application. All major data logic occurs here.

• Architecture: Strict MVC-inspired separation organized by feature module (auth, halls, dining, admission, inventory, finance).
• Stack: Node.js, Express 5.2+ (native async error support), TypeScript execution via tsx.
• Database: MySQL 8, manipulated via Drizzle ORM (drizzle-orm). if there is any change in the schema of db, then the ER_DIAGRAM must be updated accordingly. The ER_DIAGRAM is present in the root of the backend folder.
• Data Validation: Zod schema validation managed strictly in middleware.
• File Structure & Conventions:
  • src/modules/<feature>/<feature>.routes.ts: Maps HTTP methods to controllers and binds middlewares.
  • src/modules/<feature>/<feature>.controller.ts: Main logic block (DO NOT write logic in pure SQL; strictly use Drizzle).
  • src/modules/<feature>/<feature>.validators.ts: Zod schemas for body, params, query. Validated with a custom validateRequest middleware.
  • src/db/models/*.ts: Central definition for DB tables and schemas.
  • src/utils/ApiError.ts and src/utils/ApiResponse.ts: Strictly wrap outgoing data in ApiResponse and throw HTTP errors using new ApiError(status, message).
• DB Modules Overview:
  • Auth: users, refreshTokens, hallStudents, hallAdmins. (Multiple role enums: PROVOST, STUDENT, ASST_FINANCE, etc.)
  • Dining: mealMenus, mealTokens, mealPayments.
  • Inventory: rooms, assets, damageReports.
  • Finance: studentDues, payments, expenses.
  • Admission: seatApplications, seatAllocations.
• Run/Port: Exposed internally/externally on Port 8000.

4. pay/ (Payment Microservice)

• Role: A lightweight, isolated Node.js/Express server used exclusively to handle payment verifications securely.
• Stack: Express 5.2+, TypeScript (tsx).
• Security: Checks token validity with the main backend.
• Run/Port: Listens internally on Port 8080.

🗄️ Infrastructure Details & Docker Compose

The system is heavily containerized.

• docker-compose.local.yml: Uses a local MySQL database mapped to 3307 externally, but internally services call 3306.
• Reverse Proxy: Nginx combines traffic across services.
• Communication Pattern: Frontends communicate with the backend via REST. The backend and pay sub-services communicate on the internal docker network (hallnet).

⚠️ Critical Agent Rules

When making edits as an AI against this repository, follow these precise rules:

1. Never write raw SQL files: All schema modifications MUST occur within backend/src/db/models/*.ts and be deployed using npx drizzle-kit generate and push inside the backend folder.
2. Respect the UI Library Boundaries:
   • While generating components for web/, bias toward HeroUI.
   • While generating components for admin/, use Radix UI primitives combined carefully with Tailwind CSS v4.
3. API Logic Formatting: In the backend, do not use try/catch internally if not explicitly necessary; rely on Express 5's async error handling mechanism. Just throw throw new ApiError(StatusCode, Message).
4. Validation Pipeline: In backend feature creation, define the Zod schema first in validators.ts, bind the schema to the route using validateRequest(schema), and finally implement the Controller relying on the fact that req.body is fully validated.

This project context acts as your singular point of truth for maintaining the codebase without polluting it with disjointed patterns or anti-patterns.