# pointfex/pointfex-erp-full-stack architecture

> Architecture diagram of the GitHub repository pointfex/pointfex-erp-full-stack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pointfex/pointfex-erp-full-stack
- Repository: https://github.com/pointfex/pointfex-erp-full-stack

## Overview

Pointfex is a role-governed ERP for staff and executives. Users authenticate through the React application, then work with tasks, projects, finance, reports, and organizational access; the NestJS API enforces permissions and persists domain state. The README documents additional governance, audit, and KPI/XP capabilities. Edges for those capabilities reflect that documentation; sampled source confirms selected controller-to-service and UI routing relationships, but unsampled wiring is not inferred.

Main entry points: [`backend/src/app.module.ts`](https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/app.module.ts) (NestJS API), [`frontend/src/App.tsx`](https://github.com/pointfex/pointfex-erp-full-stack/blob/main/frontend/src/App.tsx) (React ERP), [`backend/src/performance/kpi-engine.service.ts`](https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/performance/kpi-engine.service.ts) (KPI and XP engine), [`frontend/src/context/AppContext.tsx`](https://github.com/pointfex/pointfex-erp-full-stack/blob/main/frontend/src/context/AppContext.tsx) (App state and API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client application"]
  node_spa["React ERP<br/>[App.tsx]"]
  node_appstate["App state and API<br/>[AppContext.tsx]"]
  node_loginui["Login and security UI<br/>[LoginPage.tsx]"]
  node_taskui["Role task views"]
end

subgraph group_identity["Identity and access"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_rbac["Authorization and roles"]
  node_accessguard["Permission enforcement"]
end

subgraph group_operations["ERP operations"]
  node_employees["Employee directory"]
  node_projects["Projects and proposals"]
  node_tasks["Task workflows<br/>[tasks.service.ts]"]
  node_finance["Finance and budgets<br/>[finance.service.ts]"]
  node_reports["Reports<br/>[reports.service.ts]"]
  node_engineering["Quality and security alerts"]
end

subgraph group_governance["Governance and performance"]
  node_governance["Voting and approvals"]
  node_kpi["KPI and XP engine"]
  node_pureengine["KPI calculation engine<br/>[xp-engine.ts]"]
  node_ledger["XP ledger"]
  node_audit["Tamper-evident audit"]
end

subgraph group_platform["API and persistence"]
  node_api["NestJS API<br/>[app.module.ts]"]
  node_dbclient["Prisma persistence<br/>[prisma.service.ts]"]
  node_database[("PostgreSQL")]
end

node_staff(("Staff and executives"))

node_staff -->|"uses"| node_spa
node_spa -->|"routes to"| node_loginui
node_spa -->|"provides state"| node_appstate
node_spa -->|"routes to"| node_taskui
node_appstate -->|"calls API"| node_api
node_loginui -->|"authenticates via"| node_auth
node_api -->|"routes auth"| node_auth
node_auth -->|"loads access profile"| node_rbac
node_api -->|"enforces access"| node_accessguard
node_accessguard -->|"resolves permissions"| node_rbac
node_api -->|"serves directory"| node_employees
node_api -->|"routes project work"| node_projects
node_api -->|"routes task work"| node_tasks
node_taskui -->|"reads task data"| node_appstate
node_api -->|"serves finance"| node_finance
node_api -->|"serves reports"| node_reports
node_api -->|"serves quality controls"| node_engineering
node_api -->|"supports executive votes"| node_governance
node_api -->|"runs KPI workflows"| node_kpi
node_kpi -->|"applies calculations"| node_pureengine
node_kpi -->|"records XP"| node_ledger
node_api -->|"records audit events"| node_audit
node_api -->|"uses Prisma"| node_dbclient
node_dbclient -->|"reads and writes"| node_database
node_audit -->|"appends audit trail"| node_database
node_ledger -->|"stores ledger events"| node_database

click node_spa "https://github.com/pointfex/pointfex-erp-full-stack/blob/main/frontend/src/App.tsx"
click node_appstate "https://github.com/pointfex/pointfex-erp-full-stack/blob/main/frontend/src/context/AppContext.tsx"
click node_loginui "https://github.com/pointfex/pointfex-erp-full-stack/blob/main/frontend/src/pages/auth/LoginPage.tsx"
click node_taskui "https://github.com/pointfex/pointfex-erp-full-stack/blob/main/frontend/src/pages/developer/DeveloperTasksPage.tsx"
click node_auth "https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/auth/auth.service.ts"
click node_rbac "https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/rbac/authorization.service.ts"
click node_accessguard "https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/common/permissions.guard.ts"
click node_employees "https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/employees/employees.service.ts"
click node_projects "https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/projects/projects.service.ts"
click node_tasks "https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/tasks/tasks.service.ts"
click node_finance "https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/finance/finance.service.ts"
click node_reports "https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/reports/reports.service.ts"
click node_engineering "https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/engineering/engineering.service.ts"
click node_governance "https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/governance/vote-engine.service.ts"
click node_kpi "https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/performance/kpi-engine.service.ts"
click node_pureengine "https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/performance/kpi-engine/xp-engine.ts"
click node_ledger "https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/performance/xp-ledger.service.ts"
click node_audit "https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/common/audit-logger.service.ts"
click node_api "https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/app.module.ts"
click node_dbclient "https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/common/prisma.service.ts"

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_spa,node_appstate,node_loginui,node_taskui toneBlue
class node_auth,node_rbac,node_accessguard toneAmber
class node_employees,node_projects,node_tasks,node_finance,node_reports,node_engineering toneMint
class node_governance,node_kpi,node_pureengine,node_ledger,node_audit toneRose
class node_api,node_dbclient,node_database,node_staff toneIndigo
```

## Components

### Client application

- [React ERP](https://github.com/pointfex/pointfex-erp-full-stack/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [App state and API](https://github.com/pointfex/pointfex-erp-full-stack/blob/main/frontend/src/context/AppContext.tsx): `frontend/src/context/AppContext.tsx`
- [Login and security UI](https://github.com/pointfex/pointfex-erp-full-stack/blob/main/frontend/src/pages/auth/LoginPage.tsx): `frontend/src/pages/auth/LoginPage.tsx`
- [Role task views](https://github.com/pointfex/pointfex-erp-full-stack/blob/main/frontend/src/pages/developer/DeveloperTasksPage.tsx): `frontend/src/pages/developer/DeveloperTasksPage.tsx`

### Identity and access

- [Authentication](https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/auth/auth.service.ts): `backend/src/auth/auth.service.ts`
- [Authorization and roles](https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/rbac/authorization.service.ts): `backend/src/rbac/authorization.service.ts`
- [Permission enforcement](https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/common/permissions.guard.ts): `backend/src/common/permissions.guard.ts`

### ERP operations

- [Employee directory](https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/employees/employees.service.ts): `backend/src/employees/employees.service.ts`
- [Projects and proposals](https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/projects/projects.service.ts): `backend/src/projects/projects.service.ts`
- [Task workflows](https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/tasks/tasks.service.ts): `backend/src/tasks/tasks.service.ts`
- [Finance and budgets](https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/finance/finance.service.ts): `backend/src/finance/finance.service.ts`
- [Reports](https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/reports/reports.service.ts): `backend/src/reports/reports.service.ts`
- [Quality and security alerts](https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/engineering/engineering.service.ts): `backend/src/engineering/engineering.service.ts`

### Governance and performance

- [Voting and approvals](https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/governance/vote-engine.service.ts): `backend/src/governance/vote-engine.service.ts`
- [KPI and XP engine](https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/performance/kpi-engine.service.ts): `backend/src/performance/kpi-engine.service.ts`
- [KPI calculation engine](https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/performance/kpi-engine/xp-engine.ts): `backend/src/performance/kpi-engine/xp-engine.ts`
- [XP ledger](https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/performance/xp-ledger.service.ts): `backend/src/performance/xp-ledger.service.ts`
- [Tamper-evident audit](https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/common/audit-logger.service.ts): `backend/src/common/audit-logger.service.ts`

### API and persistence

- [NestJS API](https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/app.module.ts): `backend/src/app.module.ts`
- [Prisma persistence](https://github.com/pointfex/pointfex-erp-full-stack/blob/main/backend/src/common/prisma.service.ts): `backend/src/common/prisma.service.ts`
- **PostgreSQL**

### Other components

- **Staff and executives**

## Connections

- Staff and executives → React ERP: uses (evidence: `README.md`)
- React ERP → Login and security UI: routes to (evidence: `frontend/src/App.tsx`)
- React ERP → App state and API: provides state (evidence: `frontend/src/App.tsx`)
- React ERP → Role task views: routes to (evidence: `frontend/src/App.tsx`)
- App state and API → NestJS API: calls API (evidence: `frontend/src/context/AppContext.tsx`)
- Login and security UI → Authentication: authenticates via (evidence: `README.md`)
- NestJS API → Authentication: routes auth (evidence: `backend/src/auth/auth.service.ts`)
- Authentication → Authorization and roles: loads access profile (evidence: `backend/src/auth/auth.service.ts`)
- NestJS API → Permission enforcement: enforces access (evidence: `README.md`)
- Permission enforcement → Authorization and roles: resolves permissions (evidence: `backend/src/common/permissions.guard.ts`)
- NestJS API → Employee directory: serves directory (evidence: `README.md`)
- NestJS API → Projects and proposals: routes project work
- NestJS API → Task workflows: routes task work
- Role task views → App state and API: reads task data (evidence: `frontend/src/pages/developer/DeveloperTasksPage.tsx`)
- NestJS API → Finance and budgets: serves finance (evidence: `README.md`)
- NestJS API → Reports: serves reports (evidence: `README.md`)
- NestJS API → Quality and security alerts: serves quality controls
- NestJS API → Voting and approvals: supports executive votes (evidence: `README.md`)
- NestJS API → KPI and XP engine: runs KPI workflows (evidence: `README.md`)
- KPI and XP engine → KPI calculation engine: applies calculations (evidence: `backend/src/performance/kpi-engine.service.ts`)
- KPI and XP engine → XP ledger: records XP (evidence: `README.md`)
- NestJS API → Tamper-evident audit: records audit events (evidence: `README.md`)
- NestJS API → Prisma persistence: uses Prisma (evidence: `README.md`)
- Prisma persistence → PostgreSQL: reads and writes (evidence: `README.md`)
- Tamper-evident audit → PostgreSQL: appends audit trail (evidence: `README.md`)
- XP ledger → PostgreSQL: stores ledger events (evidence: `README.md`)
