# fjdvm/epic-crms architecture

> Architecture diagram of the GitHub repository fjdvm/epic-crms, 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/fjdvm/epic-crms
- Repository: https://github.com/fjdvm/epic-crms

## Overview

CREOMS is a staff-facing commerce operations system; sign-in and session validation are delegated to the Portal. Staff use its protected pages to manage orders, returns, customer profiles, tickets, approvals, and settings, with dashboards and reports for oversight. The graph includes major feature areas and shared database, AI, and gateway layers. Several subsystems are represented by their exact feature directories because their implementation was not sampled; their relationships are shown only where the source index or excerpts provide evidence.

Main entry points: [`features/approvals/server.ts`](https://github.com/fjdvm/epic-crms/blob/main/features/approvals/server.ts) (Approval workflow), [`lib/crms-db.ts`](https://github.com/fjdvm/epic-crms/blob/main/lib/crms-db.ts) (CREOMS database), [`features/orders/payment-review-actions.ts`](https://github.com/fjdvm/epic-crms/blob/main/features/orders/payment-review-actions.ts) (Payment review), [`lib/gateway.ts`](https://github.com/fjdvm/epic-crms/blob/main/lib/gateway.ts) (API gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Portal access"]
  node_portal_routes["Portal routes"]
  node_portal_client["Portal client<br/>[client.ts]"]
  node_staff_access["Staff access<br/>[staff.ts]"]
  node_roles["Role checks<br/>[roles.ts]"]
  node_app_shell["App shell<br/>[app-shell.tsx]"]
end

subgraph group_operations["Commerce operations"]
  node_orders["Order operations"]
  node_payments["Payment review"]
  node_returns["Returns operations"]
  node_fulfilment["Fulfilment<br/>[fulfilment.ts]"]
  node_approvals["Approval workflow<br/>[server.ts]"]
  node_proof_reader["Payment proof reader<br/>[proof-reader.ts]"]
end

subgraph group_service["Customer service"]
  node_profiles["Customer profiles"]
  node_tickets["Ticket operations"]
  node_feedback["Feedback analysis"]
  node_notifications["Notifications"]
  node_service_levels["Service levels"]
end

subgraph group_insight["Insights and oversight"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_reports["Operational reports"]
end

subgraph group_infrastructure["Shared infrastructure"]
  node_crms_db[("CREOMS database<br/>[crms-db.ts]")]
  node_storefront_db[("Storefront database<br/>[db.ts]")]
  node_tickets_db[("Tickets database<br/>[tickets-db.ts]")]
  node_gateway{{"API gateway<br/>[gateway.ts]"}}
  node_ai["Structured AI<br/>[structured.ts]"]
end

node_staff(("Staff user"))
node_portal{{"Portal service"}}

node_staff -->|"signs in"| node_portal_routes
node_portal_routes -->|"exchanges code"| node_portal_client
node_portal_client -->|"validates session"| node_portal
node_staff_access -->|"checks session"| node_portal_client
node_staff_access -->|"checks role"| node_roles
node_staff -.->|"uses"| node_app_shell
node_app_shell -.->|"guards pages"| node_staff_access
node_staff -.->|"manages orders"| node_orders
node_staff -.->|"reviews payments"| node_payments
node_staff -.->|"handles returns"| node_returns
node_staff -.->|"manages fulfilment"| node_fulfilment
node_staff -.->|"reviews requests"| node_approvals
node_staff -.->|"manages profiles"| node_profiles
node_staff -->|"handles tickets"| node_tickets
node_staff -.->|"reviews feedback"| node_feedback
node_staff -->|"views metrics"| node_dashboard
node_staff -->|"views reports"| node_reports
node_approvals -->|"reads and writes"| node_crms_db
node_approvals -->|"records audit"| node_gateway
node_approvals -->|"notifies recipients"| node_portal
node_approvals -->|"decides cancellation"| node_orders
node_tickets -->|"loads ticket data"| node_tickets_db
node_tickets -->|"loads targets"| node_service_levels
node_service_levels -->|"reads and writes"| node_crms_db
node_payments -->|"reads and writes"| node_crms_db
node_payments -->|"records audit"| node_gateway
node_payments -->|"checks settings"| node_service_levels
node_proof_reader -->|"analyzes proof"| node_ai
node_dashboard -->|"loads metrics"| node_crms_db
node_notifications -->|"syncs events"| node_crms_db
node_notifications -->|"syncs ticket events"| node_tickets_db
node_notifications -->|"reads customer events"| node_storefront_db
node_orders -.->|"uses gateway"| node_gateway
node_returns -.->|"uses gateway"| node_gateway

click node_portal_routes "https://github.com/fjdvm/epic-crms/tree/main/app/api/portal"
click node_portal_client "https://github.com/fjdvm/epic-crms/blob/main/lib/portal/client.ts"
click node_staff_access "https://github.com/fjdvm/epic-crms/blob/main/lib/portal/staff.ts"
click node_roles "https://github.com/fjdvm/epic-crms/blob/main/lib/portal/roles.ts"
click node_app_shell "https://github.com/fjdvm/epic-crms/blob/main/components/layout/app-shell.tsx"
click node_orders "https://github.com/fjdvm/epic-crms/tree/main/features/orders"
click node_payments "https://github.com/fjdvm/epic-crms/blob/main/features/orders/payment-review-actions.ts"
click node_returns "https://github.com/fjdvm/epic-crms/tree/main/features/returns"
click node_fulfilment "https://github.com/fjdvm/epic-crms/blob/main/features/orders/fulfilment.ts"
click node_approvals "https://github.com/fjdvm/epic-crms/blob/main/features/approvals/server.ts"
click node_profiles "https://github.com/fjdvm/epic-crms/tree/main/features/customer-profiles"
click node_tickets "https://github.com/fjdvm/epic-crms/tree/main/features/tickets"
click node_feedback "https://github.com/fjdvm/epic-crms/tree/main/features/feedback"
click node_notifications "https://github.com/fjdvm/epic-crms/tree/main/features/notifications"
click node_dashboard "https://github.com/fjdvm/epic-crms/blob/main/app/(app)/dashboard/page.tsx"
click node_reports "https://github.com/fjdvm/epic-crms/tree/main/features/reports"
click node_crms_db "https://github.com/fjdvm/epic-crms/blob/main/lib/crms-db.ts"
click node_storefront_db "https://github.com/fjdvm/epic-crms/blob/main/lib/db.ts"
click node_tickets_db "https://github.com/fjdvm/epic-crms/blob/main/lib/tickets-db.ts"
click node_gateway "https://github.com/fjdvm/epic-crms/blob/main/lib/gateway.ts"
click node_ai "https://github.com/fjdvm/epic-crms/blob/main/lib/ai/structured.ts"
click node_proof_reader "https://github.com/fjdvm/epic-crms/blob/main/features/orders/proof-reader.ts"
click node_service_levels "https://github.com/fjdvm/epic-crms/blob/main/features/tickets/service-level-store.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_portal_routes,node_portal_client,node_staff_access,node_roles,node_app_shell,node_staff toneBlue
class node_orders,node_payments,node_returns,node_fulfilment,node_approvals,node_proof_reader toneAmber
class node_profiles,node_tickets,node_feedback,node_notifications,node_service_levels toneMint
class node_dashboard,node_reports toneRose
class node_crms_db,node_storefront_db,node_tickets_db,node_gateway,node_ai,node_portal toneIndigo
```

## Components

### Portal access

- [Portal routes](https://github.com/fjdvm/epic-crms/tree/main/app/api/portal): `app/api/portal`
- [Portal client](https://github.com/fjdvm/epic-crms/blob/main/lib/portal/client.ts): `lib/portal/client.ts`
- [Staff access](https://github.com/fjdvm/epic-crms/blob/main/lib/portal/staff.ts): `lib/portal/staff.ts`
- [Role checks](https://github.com/fjdvm/epic-crms/blob/main/lib/portal/roles.ts): `lib/portal/roles.ts`
- [App shell](https://github.com/fjdvm/epic-crms/blob/main/components/layout/app-shell.tsx): `components/layout/app-shell.tsx`

### Commerce operations

- [Order operations](https://github.com/fjdvm/epic-crms/tree/main/features/orders): `features/orders`
- [Payment review](https://github.com/fjdvm/epic-crms/blob/main/features/orders/payment-review-actions.ts): `features/orders/payment-review-actions.ts`
- [Returns operations](https://github.com/fjdvm/epic-crms/tree/main/features/returns): `features/returns`
- [Fulfilment](https://github.com/fjdvm/epic-crms/blob/main/features/orders/fulfilment.ts): `features/orders/fulfilment.ts`
- [Approval workflow](https://github.com/fjdvm/epic-crms/blob/main/features/approvals/server.ts): `features/approvals/server.ts`
- [Payment proof reader](https://github.com/fjdvm/epic-crms/blob/main/features/orders/proof-reader.ts): `features/orders/proof-reader.ts`

### Customer service

- [Customer profiles](https://github.com/fjdvm/epic-crms/tree/main/features/customer-profiles): `features/customer-profiles`
- [Ticket operations](https://github.com/fjdvm/epic-crms/tree/main/features/tickets): `features/tickets`
- [Feedback analysis](https://github.com/fjdvm/epic-crms/tree/main/features/feedback): `features/feedback`
- [Notifications](https://github.com/fjdvm/epic-crms/tree/main/features/notifications): `features/notifications`
- [Service levels](https://github.com/fjdvm/epic-crms/blob/main/features/tickets/service-level-store.ts): `features/tickets/service-level-store.ts`

### Insights and oversight

- [Dashboard](https://github.com/fjdvm/epic-crms/blob/main/app/(app)/dashboard/page.tsx): `app/(app)/dashboard/page.tsx`
- [Operational reports](https://github.com/fjdvm/epic-crms/tree/main/features/reports): `features/reports`

### Shared infrastructure

- [CREOMS database](https://github.com/fjdvm/epic-crms/blob/main/lib/crms-db.ts): `lib/crms-db.ts`
- [Storefront database](https://github.com/fjdvm/epic-crms/blob/main/lib/db.ts): `lib/db.ts`
- [Tickets database](https://github.com/fjdvm/epic-crms/blob/main/lib/tickets-db.ts): `lib/tickets-db.ts`
- [API gateway](https://github.com/fjdvm/epic-crms/blob/main/lib/gateway.ts): `lib/gateway.ts`
- [Structured AI](https://github.com/fjdvm/epic-crms/blob/main/lib/ai/structured.ts): `lib/ai/structured.ts`

### Other components

- **Staff user**
- **Portal service**

## Connections

- Staff user → Portal routes: signs in (evidence: `README.md`)
- Portal routes → Portal client: exchanges code (evidence: `app/api/portal/callback/route.ts`)
- Portal client → Portal service: validates session (evidence: `lib/portal/client.ts`)
- Staff access → Portal client: checks session (evidence: `lib/portal/staff.ts`)
- Staff access → Role checks: checks role (evidence: `lib/portal/staff.ts`)
- Staff user → App shell: uses
- App shell → Staff access: guards pages
- Staff user → Order operations: manages orders
- Staff user → Payment review: reviews payments
- Staff user → Returns operations: handles returns
- Staff user → Fulfilment: manages fulfilment
- Staff user → Approval workflow: reviews requests
- Staff user → Customer profiles: manages profiles
- Staff user → Ticket operations: handles tickets
- Staff user → Feedback analysis: reviews feedback
- Staff user → Dashboard: views metrics (evidence: `app/(app)/dashboard/page.tsx`)
- Staff user → Operational reports: views reports
- Approval workflow → CREOMS database: reads and writes (evidence: `features/approvals/server.ts`)
- Approval workflow → API gateway: records audit (evidence: `features/approvals/server.ts`)
- Approval workflow → Portal service: notifies recipients (evidence: `features/approvals/server.ts`)
- Approval workflow → Order operations: decides cancellation (evidence: `features/approvals/server.ts`)
- Ticket operations → Tickets database: loads ticket data (evidence: `app/(app)/tickets/page.tsx`)
- Ticket operations → Service levels: loads targets (evidence: `app/(app)/tickets/page.tsx`)
- Service levels → CREOMS database: reads and writes (evidence: `features/tickets/service-level-store.ts`)
- Payment review → CREOMS database: reads and writes (evidence: `features/orders/payment-review-actions.ts`)
- Payment review → API gateway: records audit (evidence: `features/orders/payment-review-actions.ts`)
- Payment review → Service levels: checks settings (evidence: `features/orders/payment-review-actions.ts`)
- Payment proof reader → Structured AI: analyzes proof (evidence: `features/orders/proof-reader.ts`)
- Dashboard → CREOMS database: loads metrics (evidence: `app/(app)/dashboard/page.tsx`)
- Notifications → CREOMS database: syncs events (evidence: `app/api/notifications/sync/route.ts`)
- Notifications → Tickets database: syncs ticket events (evidence: `app/api/notifications/sync/route.ts`)
- Notifications → Storefront database: reads customer events (evidence: `app/api/notifications/sync/route.ts`)
- Order operations → API gateway: uses gateway (evidence: `features/orders/payment-review-actions.ts`)
- Returns operations → API gateway: uses gateway
