# codesbydipkhan/ims_v01 architecture

> Architecture diagram of the GitHub repository codesbydipkhan/ims_v01, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/codesbydipkhan/ims_v01
- Repository: https://github.com/codesbydipkhan/ims_v01

## Overview

1. **Overall shape**
   - This is a two-tier internal management system for NextEd Advisors.
   - The **frontend** is a Next.js App Router app on port **3000**.
   - The **backend** is a NestJS REST API on port **3001**.
   - Persistence is **PostgreSQL** via **TypeORM**; files are stored locally under `backend/storage/invoices`.

2. **Frontend boundary and route structure**
   - The UI is organized by business area rather than by generic pages.
   - Main route groups include:
     - **Students**: listing, add/register flow, collected/student detail pages, transactions
     - **Invoices**: list, create, internal invoices
     - **Dashboard**: performance and confidential sections
   - The route tree suggests a multi-step operational app, not a content site.

3. **Frontend access control**
   - Authentication is enforced in the UI with `AuthGuard` and `ConfidentialGuard`.
   - The frontend stores the JWT in **sessionStorage** and uses it when calling the API.
   - Confidential pages are separated from general dashboard pages by a dedicated confidential layout.

4. **Frontend-to-backend integration**
   - `src/lib/api.ts` is the client-side API boundary.
   - The frontend talks directly to the NestJS REST endpoints using the `NEXT_PUBLIC_API_URL` environment variable.
   - This is a thin presentation layer: most business rules live in the backend.

5. **Backend module architecture**
   - The backend is split into NestJS feature modules:
     - `auth`
     - `students`
     - `employees`
     - `counselors`
     - `countries`
     - `currency`
     - `invoices`
     - `io`
     - `salary`
   - Each module follows the standard Nest pattern of **controller + service + DTOs**, with TypeORM entities in `src/entities`.

6. **Core data model**
   - The important persisted entities are:
     - `User` for login
     - `Student`, `StudentInfo`, `StudentFollowUp`
     - `Employee`, `Counselor`, `Country`
     - `Invoice`
     - `Salary`
     - `IoEntry` for income/expense tracking
     - `Sequence` for generated identifiers
   - This indicates a workflow-centric domain model, with students and finance as the primary records.

7. **Authentication flow**
   - Login happens through `POST /auth/login`.
   - The backend uses **JWT auth** with a NestJS strategy and guard.
   - A `Public` decorator marks unauthenticated routes.
   - The current design is database-backed credential verification with bcrypt-hashed passwords, not SSO or external identity.

8. **Student lifecycle**
   - Student registration is a staged process in the UI:
     - collect info
     - register
     - view collected record
     - view full student detail
     - track transactions
   - Backend endpoints support create, list, detail, and partial update operations.
   - Student IDs are auto-generated using business prefixes and a sequence mechanism, which means identity generation is part of the application logic, not the database alone.

9. **Invoice and PDF pipeline**
   - Invoice creation is handled by the backend and produces both a database record and a PDF file.
   - `PdfService` uses **Puppeteer** to render PDFs.
   - Generated PDFs are stored locally and can be streamed back inline from `GET /invoices/:id/pdf`.
   - The README notes a future Firebase Storage swap point, but the current architecture is local file storage.

10. **Currency and finance-related flow**
   - The backend has a dedicated `currency` module for live conversion to BDT.
   - It prefers an exchange-rate API key if configured, otherwise falls back to `open.er-api.com`.
   - This conversion capability feeds invoice-related calculations and finance views.

11. **Operational/confidential subsystems**
   - The dashboard includes **performance** and **confidential** areas, implying separate access levels for sensitive financial reporting.
   - `io` and `salary` modules suggest internal bookkeeping and payroll-style records.
   - These areas likely consume the same core entities but are isolated at the route/UI level.

12. **Startup and environment dependencies**
   - The backend reads database, JWT, exchange-rate, and PDF storage settings from `backend/.env`.
   - TypeORM is configured with `synchronize: true`, so schema creation happens automatically on startup.
   - A seed script initializes the system with an admin user, countries, and employees, which is important for first-run architecture.

13. **External and runtime dependencies that matter**
   - **PostgreSQL** is the primary durable store.
   - **Puppeteer/Chromium** is a runtime dependency for PDF generation.
   - **Exchange-rate HTTP APIs** are used for live currency conversion.
   - No queueing layer, cache, or separate reporting service is present in the repository.

14. **What to draw in an architecture diagram**
   - Show the **Next.js frontend** as the presentation layer with guarded routes.
   - Show the **NestJS API** as the central business logic layer, split into domain modules.
   - Connect the backend to **PostgreSQL**, **local PDF storage**, and external **exchange-rate APIs**.
   - Highlight the data flows for **login**, **student registration**, **invoice creation/PDF generation**, and **finance/confidential reporting** as the main application paths.

Main entry points: [`backend/src/main.ts`](https://github.com/codesbydipkhan/ims_v01/blob/master/backend/src/main.ts) (Nest API), [`backend/src/invoices`](https://github.com/codesbydipkhan/ims_v01/tree/master/backend/src/invoices) (Invoices module), [`frontend/src/app`](https://github.com/codesbydipkhan/ims_v01/tree/master/frontend/src/app) (Next.js app), [`backend/src`](https://github.com/codesbydipkhan/ims_v01/tree/master/backend/src) (Finance modules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_ui_root["Next.js app"]
  node_ui_students["Students<br/>route group"]
  node_ui_invoices["Invoices<br/>route group"]
  node_ui_dashboard["Dashboard<br/>route group"]
  node_ui_guards{{"Route guards<br/>auth guards"}}
  node_ui_api["API client<br/>HTTP client<br/>[api.ts]"]
end

subgraph group_backend["Backend"]
  node_api_root["Nest API<br/>NestJS REST API<br/>[main.ts]"]
  node_api_auth{{"Auth"}}
  node_api_students{{"Students module"}}
  node_api_invoices{{"Invoices module"}}
  node_api_finance{{"Finance modules"}}
  node_api_entities[("Entities<br/>TypeORM models")]
end

subgraph group_data["Data & runtime"]
  node_db[("PostgreSQL<br/>database")]
  node_pdf_store["Invoice files<br/>local storage"]
  node_exchange_api(("Rates API<br/>external HTTP API"))
  node_chromium(("Puppeteer<br/>PDF runtime"))
end

node_ui_root -->|"routes"| node_ui_students
node_ui_root -->|"routes"| node_ui_invoices
node_ui_root -->|"routes"| node_ui_dashboard
node_ui_students -.->|"protected by"| node_ui_guards
node_ui_dashboard -.->|"protected by"| node_ui_guards
node_ui_root -->|"calls"| node_ui_api
node_ui_api -->|"HTTP"| node_api_root
node_api_root -->|"loads"| node_api_auth
node_api_root -->|"loads"| node_api_students
node_api_root -->|"loads"| node_api_invoices
node_api_root -->|"loads"| node_api_finance
node_api_root -->|"uses"| node_api_entities
node_api_auth -->|"reads/writes"| node_db
node_api_students -->|"reads/writes"| node_db
node_api_students -->|"maps to"| node_api_entities
node_api_invoices -->|"renders PDFs"| node_chromium
node_api_invoices -->|"stores files"| node_pdf_store
node_api_invoices -->|"reads/writes"| node_db
node_api_finance -->|"fetches rates"| node_exchange_api
node_api_finance -->|"reads/writes"| node_db
node_api_finance -->|"maps to"| node_api_entities
node_api_auth -.->|"JWT session"| node_ui_api
node_api_invoices -->|"serves"| node_ui_invoices

click node_ui_root "https://github.com/codesbydipkhan/ims_v01/tree/master/frontend/src/app"
click node_ui_students "https://github.com/codesbydipkhan/ims_v01/tree/master/frontend/src/app/students"
click node_ui_invoices "https://github.com/codesbydipkhan/ims_v01/tree/master/frontend/src/app/invoices"
click node_ui_dashboard "https://github.com/codesbydipkhan/ims_v01/tree/master/frontend/src/app/dashboard"
click node_ui_guards "https://github.com/codesbydipkhan/ims_v01/tree/master/frontend/src/components"
click node_ui_api "https://github.com/codesbydipkhan/ims_v01/blob/master/frontend/src/lib/api.ts"
click node_api_root "https://github.com/codesbydipkhan/ims_v01/blob/master/backend/src/main.ts"
click node_api_auth "https://github.com/codesbydipkhan/ims_v01/tree/master/backend/src/auth"
click node_api_students "https://github.com/codesbydipkhan/ims_v01/tree/master/backend/src/students"
click node_api_invoices "https://github.com/codesbydipkhan/ims_v01/tree/master/backend/src/invoices"
click node_api_finance "https://github.com/codesbydipkhan/ims_v01/tree/master/backend/src"
click node_api_entities "https://github.com/codesbydipkhan/ims_v01/tree/master/backend/src/entities"
click node_pdf_store "https://github.com/codesbydipkhan/ims_v01/tree/master/backend/storage/invoices"

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_ui_root,node_ui_students,node_ui_invoices,node_ui_dashboard,node_ui_guards,node_ui_api toneBlue
class node_api_root,node_api_auth,node_api_students,node_api_invoices,node_api_finance,node_api_entities toneAmber
class node_db,node_pdf_store,node_exchange_api,node_chromium toneMint
```

## Components

### Frontend

Next.js presentation layer with guarded operational routes.

- [Next.js app](https://github.com/codesbydipkhan/ims_v01/tree/master/frontend/src/app): Next.js App Router UI · Frontend shell for the internal management system. · `frontend/src/app`
- [Students](https://github.com/codesbydipkhan/ims_v01/tree/master/frontend/src/app/students): route group · Student onboarding, collected records, detail views, and transactions. · `frontend/src/app/students`
- [Invoices](https://github.com/codesbydipkhan/ims_v01/tree/master/frontend/src/app/invoices): route group · Invoice listing, creation, and internal invoice flows. · `frontend/src/app/invoices`
- [Dashboard](https://github.com/codesbydipkhan/ims_v01/tree/master/frontend/src/app/dashboard): route group · Performance and confidential dashboard areas. · `frontend/src/app/dashboard`
- [Route guards](https://github.com/codesbydipkhan/ims_v01/tree/master/frontend/src/components): auth guards · AuthGuard and ConfidentialGuard enforce UI access control. · `frontend/src/components`
- [API client](https://github.com/codesbydipkhan/ims_v01/blob/master/frontend/src/lib/api.ts): HTTP client · Client-side API boundary using the configured API URL and session JWT. · `frontend/src/lib/api.ts`

### Backend

NestJS API and domain modules.

- [Nest API](https://github.com/codesbydipkhan/ims_v01/blob/master/backend/src/main.ts): NestJS REST API · Backend application and HTTP entrypoint. · `backend/src/main.ts`
- [Auth](https://github.com/codesbydipkhan/ims_v01/tree/master/backend/src/auth): module · Login, JWT strategy, public routes, and credential verification. · `backend/src/auth`
- [Students module](https://github.com/codesbydipkhan/ims_v01/tree/master/backend/src/students): module · Student registration, detail, and update workflows. · `backend/src/students`
- [Invoices module](https://github.com/codesbydipkhan/ims_v01/tree/master/backend/src/invoices): module · Invoice creation, internal invoices, and PDF generation. · `backend/src/invoices`
- [Finance modules](https://github.com/codesbydipkhan/ims_v01/tree/master/backend/src): modules · Employees, counselors, countries, currency, io, and salary domain modules. · `backend/src`
- [Entities](https://github.com/codesbydipkhan/ims_v01/tree/master/backend/src/entities): TypeORM models · Persistent domain models including users, students, invoices, finance, and sequences. · `backend/src/entities`

### Data & runtime

Persistence, file storage, and external runtime dependencies.

- **PostgreSQL**: database · Primary durable store accessed through TypeORM.
- [Invoice files](https://github.com/codesbydipkhan/ims_v01/tree/master/backend/storage/invoices): local storage · Generated invoice PDFs stored under backend/storage/invoices. · `backend/storage/invoices`
- **Rates API**: external HTTP API · Fallback/live exchange-rate source used by currency conversion.
- **Puppeteer**: PDF runtime · HTML-to-PDF rendering runtime used by invoice generation.

## Connections

- Next.js app → Students: routes · Business-area route tree for student workflows.
- Next.js app → Invoices: routes · Invoice-focused UI flows.
- Next.js app → Dashboard: routes · Dashboard and sensitive reporting areas.
- Students → Route guards: protected by · Student routes require UI authentication.
- Dashboard → Route guards: protected by · Confidential dashboard routes are separately guarded.
- Next.js app → API client: calls · Frontend uses the API client as its backend boundary.
- API client → Nest API: HTTP · Direct REST calls to the NestJS backend.
- Nest API → Auth: loads · Authentication feature module.
- Nest API → Students module: loads · Student workflow module.
- Nest API → Invoices module: loads · Invoice and PDF workflow module.
- Nest API → Finance modules: loads · Operational finance-related modules.
- Nest API → Entities: uses · Shared persistence models.
- Auth → PostgreSQL: reads/writes · Credential verification and user lookup.
- Students module → PostgreSQL: reads/writes · Student records and follow-up data.
- Students module → Entities: maps to · Student, StudentInfo, StudentFollowUp, and Sequence entities.
- Invoices module → Puppeteer: renders PDFs · Invoice PDFs are generated from backend templates.
- Invoices module → Invoice files: stores files · Generated PDFs are persisted locally.
- Invoices module → PostgreSQL: reads/writes · Invoice records and identifiers.
- Finance modules → Rates API: fetches rates · Currency conversion uses live exchange-rate services.
- Finance modules → PostgreSQL: reads/writes · Finance, employee, counselor, and IO records.
- Finance modules → Entities: maps to · Employee, Counselor, Country, Salary, and IoEntry entities.
- Auth → API client: JWT session · Frontend stores and sends the token from sessionStorage.
- Invoices module → Invoices: serves · Invoice creation and PDF views are driven by backend endpoints.