# ittldigitalization/prm-ittl architecture

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

- Interactive diagram: https://gitdiagram.com/ittldigitalization/prm-ittl
- Repository: https://github.com/ittldigitalization/prm-ittl

## Overview

#### Purpose and Runtime Topology
EPMS is a project-management system for operational delivery: projects, tasks, milestones, Gantt planning, DPRs, teams, customers, budgets, billing, documents, issues, and AMC contract workflows. It runs as a React/Vite browser client plus a Node.js/Express TypeScript server, with Supabase providing PostgreSQL and authentication. Primary runtime entry points are `client/src/main.tsx` and `server/src/index.ts`.

#### Client Application Shell
The frontend is the principal user-facing application. `client/src/main.tsx` bootstraps React, while `client/src/App.tsx` establishes the top-level application composition and `client/src/components/DashboardLayout.tsx` provides the shared authenticated/dashboard navigation shell. The client is built and served through Vite (`client/vite.config.ts`) and styled globally through `client/src/index.css` and `client/src/App.css`.

#### Core Project Delivery Domain
Project execution is organized around management screens for projects, tasks, milestones, schedules, and daily reporting:
- Project lifecycle and assignment: `client/src/pages/ProjectManagement.tsx`, `client/src/pages/TaskManagement.tsx`
- Schedule visualization and milestones: `client/src/pages/GanttChart.tsx`, `client/src/pages/MilestoneManagement.tsx`
- Progress reporting: `client/src/pages/DPR.tsx`

These screens form the central operational flow: define projects, decompose work into tasks/milestones, track scheduled progress, and record daily progress.

#### Commercial and Customer Domain
Customer records anchor commercial work, while budget and billing pages manage financial tracking around project delivery. Key boundaries are `client/src/pages/CustomerManagement.tsx`, `client/src/pages/BudgetManagement.tsx`, and `client/src/pages/BillingManagement.tsx`. Database evolution for this area is represented by `database/billing_migration.sql` and `database/fix_billing_budget_trigger.sql`, indicating database-side financial consistency logic.

#### Supporting Delivery Records
Documents, issues, and team data are managed as related operational records rather than standalone applications. The relevant UI modules are `client/src/pages/DocumentManagement.tsx`, `client/src/pages/IssueTracker.tsx`, and `client/src/pages/TeamManagement.tsx`. Their persistence model is evolved through `database/task_document_migration.sql`, `database/document_milestone_migration.sql`, and `database/issues_migration.sql`.

#### AMC Subsystem
AMC is a distinct workflow area with its own dashboard and entities for contracts, visits, payments, documents, and history: `client/src/pages/amc/AmcDashboard.tsx`, `client/src/pages/amc/AmcContracts.tsx`, and `client/src/pages/amc/AmcPayments.tsx`. The corresponding persistence boundary is `database/amc_migration.sql`; payment schema refinement and access-policy remediation appear in `database/alter_amc_payments_add_reference.sql` and `database/fix_amc_rls.sql`.

#### Data, Auth, and Service Boundaries
Supabase is the external database/auth service and is directly represented in the frontend integration at `client/src/lib/supabase.ts`. The database’s baseline schema is `database/schema.sql`, with incremental SQL migrations defining the authoritative relational model and row-level-security changes. Environment-driven Supabase credentials are expected by both deployment/runtime configuration (`.env.example`, `server/.env.example`). The Express server at `server/src/index.ts` is the backend process boundary; clients run on port 3000 and the API process on port 5000 in local development.

#### Authentication and Persistence UX
Authentication begins at `client/src/pages/Login.tsx` and feeds users into the dashboard shell. Browser-local persistence is abstracted by `client/src/hooks/useLocalStorage.ts`, while durable application records belong in Supabase. This creates a clear boundary: local storage supports client UX state, whereas project, commercial, AMC, and user/auth data are backend-managed.

Main entry points: [`client/src/App.tsx`](https://github.com/ittldigitalization/prm-ittl/blob/main/client/src/App.tsx) (App and dashboard shell), [`client/src/lib/supabase.ts`](https://github.com/ittldigitalization/prm-ittl/blob/main/client/src/lib/supabase.ts) (Supabase integration), [`client/src/pages/ProjectManagement.tsx`](https://github.com/ittldigitalization/prm-ittl/blob/main/client/src/pages/ProjectManagement.tsx) (Projects and tasks), [`client/src/pages/BudgetManagement.tsx`](https://github.com/ittldigitalization/prm-ittl/blob/main/client/src/pages/BudgetManagement.tsx) (Budgets and billing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React Client"]
  node_client_entry["React bootstrap<br/>client entry<br/>[main.tsx]"]
  node_app_shell["App and dashboard shell<br/>application shell<br/>[App.tsx]"]
  node_login["Login<br/>auth screen<br/>[Login.tsx]"]
  node_local_storage["Local UX state<br/>browser persistence<br/>[useLocalStorage.ts]"]
end

subgraph group_delivery["Project Delivery"]
  node_projects_tasks["Projects and tasks<br/>delivery screens"]
  node_schedule["Schedule and milestones<br/>planning screens<br/>[GanttChart.tsx]"]
  node_dpr["Daily progress reports<br/>reporting screen<br/>[DPR.tsx]"]
  node_delivery_records["Documents, issues, teams<br/>supporting records"]
end

subgraph group_commercial["Commercial"]
  node_customers["Customers<br/>customer screen"]
  node_finance["Budgets and billing<br/>financial screens"]
end

subgraph group_amc["AMC"]
  node_amc_workflow["AMC contracts and payments<br/>AMC screens<br/>[AmcContracts.tsx]"]
end

subgraph group_platform["Platform &amp; Data"]
  node_express_server{{"Express API<br/>Node.js backend<br/>[index.ts]"}}
  node_supabase_client["Supabase integration<br/>client data adapter<br/>[supabase.ts]"]
  node_supabase[("Supabase<br/>managed PostgreSQL and auth")]
  node_database_schema["Schema and migrations<br/>SQL schema<br/>[schema.sql]"]
end

node_client_entry -->|"boots"| node_app_shell
node_login -->|"authenticates into"| node_app_shell
node_app_shell -->|"hosts"| node_projects_tasks
node_app_shell -->|"hosts"| node_schedule
node_app_shell -->|"hosts"| node_dpr
node_app_shell -->|"hosts"| node_delivery_records
node_app_shell -->|"hosts"| node_customers
node_app_shell -->|"hosts"| node_finance
node_app_shell -->|"hosts"| node_amc_workflow
node_projects_tasks -->|"plans work"| node_schedule
node_projects_tasks -->|"reports progress"| node_dpr
node_customers -->|"anchors commercial work"| node_finance
node_app_shell -->|"persists UX state"| node_local_storage
node_app_shell -->|"uses"| node_supabase_client
node_supabase_client -->|"auth and data"| node_supabase
node_express_server -->|"backend access"| node_supabase
node_database_schema -.->|"defines relational model and RLS"| node_supabase
node_projects_tasks -->|"persists delivery data"| node_supabase_client
node_finance -->|"persists financial data"| node_supabase_client
node_amc_workflow -->|"persists AMC data"| node_supabase_client

click node_client_entry "https://github.com/ittldigitalization/prm-ittl/blob/main/client/src/main.tsx"
click node_app_shell "https://github.com/ittldigitalization/prm-ittl/blob/main/client/src/App.tsx"
click node_login "https://github.com/ittldigitalization/prm-ittl/blob/main/client/src/pages/Login.tsx"
click node_local_storage "https://github.com/ittldigitalization/prm-ittl/blob/main/client/src/hooks/useLocalStorage.ts"
click node_projects_tasks "https://github.com/ittldigitalization/prm-ittl/blob/main/client/src/pages/ProjectManagement.tsx"
click node_schedule "https://github.com/ittldigitalization/prm-ittl/blob/main/client/src/pages/GanttChart.tsx"
click node_dpr "https://github.com/ittldigitalization/prm-ittl/blob/main/client/src/pages/DPR.tsx"
click node_delivery_records "https://github.com/ittldigitalization/prm-ittl/blob/main/client/src/pages/DocumentManagement.tsx"
click node_customers "https://github.com/ittldigitalization/prm-ittl/blob/main/client/src/pages/CustomerManagement.tsx"
click node_finance "https://github.com/ittldigitalization/prm-ittl/blob/main/client/src/pages/BudgetManagement.tsx"
click node_amc_workflow "https://github.com/ittldigitalization/prm-ittl/blob/main/client/src/pages/amc/AmcContracts.tsx"
click node_express_server "https://github.com/ittldigitalization/prm-ittl/blob/main/server/src/index.ts"
click node_supabase_client "https://github.com/ittldigitalization/prm-ittl/blob/main/client/src/lib/supabase.ts"
click node_database_schema "https://github.com/ittldigitalization/prm-ittl/blob/main/database/schema.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_client_entry,node_app_shell,node_login,node_local_storage toneBlue
class node_projects_tasks,node_schedule,node_dpr,node_delivery_records toneAmber
class node_customers,node_finance toneMint
class node_amc_workflow toneRose
class node_express_server,node_supabase_client,node_supabase,node_database_schema toneIndigo
```

## Components

### React Client

Browser application built with Vite.

- [React bootstrap](https://github.com/ittldigitalization/prm-ittl/blob/main/client/src/main.tsx): client entry · `client/src/main.tsx`
- [App and dashboard shell](https://github.com/ittldigitalization/prm-ittl/blob/main/client/src/App.tsx): application shell · Composes routes and authenticated navigation. · `client/src/App.tsx`
- [Login](https://github.com/ittldigitalization/prm-ittl/blob/main/client/src/pages/Login.tsx): auth screen · `client/src/pages/Login.tsx`
- [Local UX state](https://github.com/ittldigitalization/prm-ittl/blob/main/client/src/hooks/useLocalStorage.ts): browser persistence · Stores client-side UX state only. · `client/src/hooks/useLocalStorage.ts`

### Project Delivery

Core execution and reporting workflows.

- [Projects and tasks](https://github.com/ittldigitalization/prm-ittl/blob/main/client/src/pages/ProjectManagement.tsx): delivery screens · Defines project lifecycle, assignments, and work items. · `client/src/pages/ProjectManagement.tsx`
- [Schedule and milestones](https://github.com/ittldigitalization/prm-ittl/blob/main/client/src/pages/GanttChart.tsx): planning screens · Visualizes plans and manages milestones. · `client/src/pages/GanttChart.tsx`
- [Daily progress reports](https://github.com/ittldigitalization/prm-ittl/blob/main/client/src/pages/DPR.tsx): reporting screen · `client/src/pages/DPR.tsx`
- [Documents, issues, teams](https://github.com/ittldigitalization/prm-ittl/blob/main/client/src/pages/DocumentManagement.tsx): supporting records · Related operational delivery records. · `client/src/pages/DocumentManagement.tsx`

### Commercial

Customer, budget, and billing management.

- [Customers](https://github.com/ittldigitalization/prm-ittl/blob/main/client/src/pages/CustomerManagement.tsx): customer screen · `client/src/pages/CustomerManagement.tsx`
- [Budgets and billing](https://github.com/ittldigitalization/prm-ittl/blob/main/client/src/pages/BudgetManagement.tsx): financial screens · Tracks project financials and billing. · `client/src/pages/BudgetManagement.tsx`

### AMC

Contract service workflow.

- [AMC contracts and payments](https://github.com/ittldigitalization/prm-ittl/blob/main/client/src/pages/amc/AmcContracts.tsx): AMC screens · Manages service contracts, visits, payments, and history. · `client/src/pages/amc/AmcContracts.tsx`

### Platform & Data

Backend process and managed persistence.

- [Express API](https://github.com/ittldigitalization/prm-ittl/blob/main/server/src/index.ts): Node.js backend · Local API process runs on port 5000. · `server/src/index.ts`
- [Supabase integration](https://github.com/ittldigitalization/prm-ittl/blob/main/client/src/lib/supabase.ts): client data adapter · Frontend integration for managed auth and data. · `client/src/lib/supabase.ts`
- **Supabase**: managed PostgreSQL and auth · Durable records, authentication, and access control.
- [Schema and migrations](https://github.com/ittldigitalization/prm-ittl/blob/main/database/schema.sql): SQL schema · Baseline schema plus domain migrations and RLS logic. · `database/schema.sql`

## Connections

- React bootstrap → App and dashboard shell: boots
- Login → App and dashboard shell: authenticates into
- App and dashboard shell → Projects and tasks: hosts
- App and dashboard shell → Schedule and milestones: hosts
- App and dashboard shell → Daily progress reports: hosts
- App and dashboard shell → Documents, issues, teams: hosts
- App and dashboard shell → Customers: hosts
- App and dashboard shell → Budgets and billing: hosts
- App and dashboard shell → AMC contracts and payments: hosts
- Projects and tasks → Schedule and milestones: plans work
- Projects and tasks → Daily progress reports: reports progress
- Customers → Budgets and billing: anchors commercial work
- App and dashboard shell → Local UX state: persists UX state
- App and dashboard shell → Supabase integration: uses
- Supabase integration → Supabase: auth and data
- Express API → Supabase: backend access
- Schema and migrations → Supabase: defines relational model and RLS
- Projects and tasks → Supabase integration: persists delivery data
- Budgets and billing → Supabase integration: persists financial data
- AMC contracts and payments → Supabase integration: persists AMC data