# ceezey/pathways architecture

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

- Interactive diagram: https://gitdiagram.com/ceezey/pathways
- Repository: https://github.com/ceezey/pathways

## Overview

PATHWAYS is a project information management platform for humanitarian and development organizations. Staff authenticate into a role- and workspace-scoped application, manage projects and delivery activities, maintain beneficiary profiles and journeys, configure metadata-driven collection, then monitor indicators and review analytics, alerts, and reports. A controlled public tracker exposes published project information. The graph preserves these distinct product stages and the rule-evaluation layer. README capabilities guide the broader map; sampled controllers confirm selected service calls, while unsampled module wiring is not inferred.

Main entry points: [`apps/web/src/app/(dashboard)/layout.tsx`](https://github.com/ceezey/pathways/blob/master/apps/web/src/app/(dashboard)/layout.tsx) (PATHWAYS workspace), [`apps/api/src/modules/activities/activities.controller.ts`](https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/activities/activities.controller.ts) (Activity operations), [`apps/api/src/modules/storage/storage.service.ts`](https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/storage/storage.service.ts) (Private file access), [`apps/web/src/features/auth/login-form.tsx`](https://github.com/ceezey/pathways/blob/master/apps/web/src/features/auth/login-form.tsx) (Sign-in workflows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and workspace"]
  node_web["PATHWAYS workspace<br/>[layout.tsx]"]
  node_web_auth["Sign-in workflows<br/>[login-form.tsx]"]
  node_auth_api["Authentication API<br/>[auth.controller.ts]"]
  node_token_auth["Token verification"]
end

subgraph group_delivery["Project delivery"]
  node_projects["Projects and activities"]
  node_activity_api["Activity operations"]
  node_beneficiaries["Beneficiary profiles"]
  node_journey["Beneficiary journeys"]
  node_finance["Budgets and expenses"]
end

subgraph group_data["Collection and monitoring"]
  node_metadata["Form metadata"]
  node_imports["Data imports<br/>[imports.service.ts]"]
  node_indicators["Indicators"]
end

subgraph group_insight["Decision and reporting"]
  node_analytics["Dashboards and analytics"]
  node_rule_engine["Rule evaluation<br/>[rule-engine.ts]"]
  node_reports["Reporting<br/>[reports.service.ts]"]
  node_public_tracker["Public project tracker<br/>[public.service.ts]"]
end

subgraph group_platform["Platform services"]
  node_supabase_auth["Supabase Auth"]
  node_database[("PostgreSQL")]
  node_storage["Supabase Storage"]
  node_storage_service["Private file access<br/>[storage.service.ts]"]
end

node_staff(("Organization staff"))

node_staff -->|"uses workspace"| node_web
node_staff -->|"signs in"| node_web_auth
node_web_auth -->|"requests access"| node_auth_api
node_auth_api -->|"verifies token"| node_token_auth
node_token_auth -->|"verifies identity"| node_supabase_auth
node_web -->|"manages projects"| node_projects
node_web -->|"records delivery"| node_activity_api
node_activity_api -->|"uses project scope"| node_projects
node_web -->|"manages profiles"| node_beneficiaries
node_web -->|"records journeys"| node_journey
node_web -->|"configures forms"| node_metadata
node_web -->|"prepares imports"| node_imports
node_web -->|"tracks indicators"| node_indicators
node_web -->|"manages finances"| node_finance
node_web -->|"reviews monitoring"| node_analytics
node_web -->|"configures decision support"| node_rule_engine
node_web -->|"creates reports"| node_reports
node_web -->|"views published projects"| node_public_tracker
node_activity_api -->|"inspects proof"| node_storage_service
node_storage_service -->|"reads private files"| node_storage
node_finance -->|"handles receipts"| node_storage_service

click node_web "https://github.com/ceezey/pathways/blob/master/apps/web/src/app/(dashboard)/layout.tsx"
click node_web_auth "https://github.com/ceezey/pathways/blob/master/apps/web/src/features/auth/login-form.tsx"
click node_auth_api "https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/auth/auth.controller.ts"
click node_token_auth "https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/auth/token-auth.service.ts"
click node_projects "https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/projects/projects.service.ts"
click node_activity_api "https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/activities/activities.controller.ts"
click node_beneficiaries "https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/beneficiaries/beneficiaries.service.ts"
click node_journey "https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/participants/participants.service.ts"
click node_metadata "https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/metadata/metadata.service.ts"
click node_imports "https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/imports/imports.service.ts"
click node_indicators "https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/indicators/indicators.service.ts"
click node_analytics "https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/dashboards/analytics.service.ts"
click node_rule_engine "https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/rules/rule-engine.ts"
click node_reports "https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/reports/reports.service.ts"
click node_public_tracker "https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/public/public.service.ts"
click node_finance "https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/finance/finance.controller.ts"
click node_storage_service "https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/storage/storage.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_web,node_web_auth,node_auth_api,node_token_auth toneBlue
class node_projects,node_activity_api,node_beneficiaries,node_journey,node_finance toneAmber
class node_metadata,node_imports,node_indicators toneMint
class node_analytics,node_rule_engine,node_reports,node_public_tracker toneRose
class node_supabase_auth,node_database,node_storage,node_storage_service,node_staff toneIndigo
```

## Components

### Access and workspace

- [PATHWAYS workspace](https://github.com/ceezey/pathways/blob/master/apps/web/src/app/(dashboard)/layout.tsx): `apps/web/src/app/(dashboard)/layout.tsx`
- [Sign-in workflows](https://github.com/ceezey/pathways/blob/master/apps/web/src/features/auth/login-form.tsx): `apps/web/src/features/auth/login-form.tsx`
- [Authentication API](https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/auth/auth.controller.ts): `apps/api/src/modules/auth/auth.controller.ts`
- [Token verification](https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/auth/token-auth.service.ts): `apps/api/src/modules/auth/token-auth.service.ts`

### Project delivery

- [Projects and activities](https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/projects/projects.service.ts): `apps/api/src/modules/projects/projects.service.ts`
- [Activity operations](https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/activities/activities.controller.ts): `apps/api/src/modules/activities/activities.controller.ts`
- [Beneficiary profiles](https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/beneficiaries/beneficiaries.service.ts): `apps/api/src/modules/beneficiaries/beneficiaries.service.ts`
- [Beneficiary journeys](https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/participants/participants.service.ts): `apps/api/src/modules/participants/participants.service.ts`
- [Budgets and expenses](https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/finance/finance.controller.ts): `apps/api/src/modules/finance/finance.controller.ts`

### Collection and monitoring

- [Form metadata](https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/metadata/metadata.service.ts): `apps/api/src/modules/metadata/metadata.service.ts`
- [Data imports](https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/imports/imports.service.ts): `apps/api/src/modules/imports/imports.service.ts`
- [Indicators](https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/indicators/indicators.service.ts): `apps/api/src/modules/indicators/indicators.service.ts`

### Decision and reporting

- [Dashboards and analytics](https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/dashboards/analytics.service.ts): `apps/api/src/modules/dashboards/analytics.service.ts`
- [Rule evaluation](https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/rules/rule-engine.ts): `apps/api/src/modules/rules/rule-engine.ts`
- [Reporting](https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/reports/reports.service.ts): `apps/api/src/modules/reports/reports.service.ts`
- [Public project tracker](https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/public/public.service.ts): `apps/api/src/modules/public/public.service.ts`

### Platform services

- **Supabase Auth**
- **PostgreSQL**
- **Supabase Storage**
- [Private file access](https://github.com/ceezey/pathways/blob/master/apps/api/src/modules/storage/storage.service.ts): `apps/api/src/modules/storage/storage.service.ts`

### Other components

- **Organization staff**

## Connections

- Organization staff → PATHWAYS workspace: uses workspace
- Organization staff → Sign-in workflows: signs in
- Sign-in workflows → Authentication API: requests access
- Authentication API → Token verification: verifies token
- Token verification → Supabase Auth: verifies identity
- PATHWAYS workspace → Projects and activities: manages projects
- PATHWAYS workspace → Activity operations: records delivery
- Activity operations → Projects and activities: uses project scope
- PATHWAYS workspace → Beneficiary profiles: manages profiles
- PATHWAYS workspace → Beneficiary journeys: records journeys
- PATHWAYS workspace → Form metadata: configures forms
- PATHWAYS workspace → Data imports: prepares imports
- PATHWAYS workspace → Indicators: tracks indicators
- PATHWAYS workspace → Budgets and expenses: manages finances
- PATHWAYS workspace → Dashboards and analytics: reviews monitoring
- PATHWAYS workspace → Rule evaluation: configures decision support
- PATHWAYS workspace → Reporting: creates reports
- PATHWAYS workspace → Public project tracker: views published projects
- Activity operations → Private file access: inspects proof
- Private file access → Supabase Storage: reads private files
- Budgets and expenses → Private file access: handles receipts