# nitinbollam/cosmos architecture

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

- Interactive diagram: https://gitdiagram.com/nitinbollam/cosmos
- Repository: https://github.com/nitinbollam/cosmos

## Overview

Cosmos is a multi-tenant ERP and distribution platform with a browser storefront, admin workspace, and mobile operations UI backed by a same-origin API. The main flow is a user action in a routed client surface, through API routing and session checks, into domain services for orders, inventory, fulfillment, finance, or other ERP work. Order orchestration coordinates payment, warehouse fulfillment, invoicing, and accounting. The README establishes the combined UI/API deployment; several product modules are represented from the source index, so their internal connections are omitted where excerpts do not verify them.

Main entry points: [`apps/web/lib/server/native-router.ts`](https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/native-router.ts) (ERP API routes), [`apps/web/server/api-router.ts`](https://github.com/nitinbollam/cosmos/blob/main/apps/web/server/api-router.ts) (HTTP API router), [`apps/web/lib/server/order-orchestration.ts`](https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/order-orchestration.ts) (Order orchestration), [`apps/client/src/router.tsx`](https://github.com/nitinbollam/cosmos/blob/main/apps/client/src/router.tsx) (Shop, admin, mobile routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client Experience"]
  node_client_app["Client application<br/>[App.tsx]"]
  node_client_routes["Shop, admin, mobile routes<br/>[router.tsx]"]
  node_shop_pages["Storefront and buyer portal<br/>[page.tsx]"]
  node_admin_pages["ERP administration"]
  node_mobile_pages["Mobile operations"]
end

subgraph group_api["API and Identity"]
  node_api_router["HTTP API router<br/>[api-router.ts]"]
  node_native_router["ERP API routes<br/>[native-router.ts]"]
  node_session["Session and access control<br/>[session.ts]"]
  node_auth["Authentication and signup<br/>[auth.ts]"]
  node_customer_context["Buyer context<br/>[buyer-context.ts]"]
  node_database[("Prisma data stores<br/>[db.ts]")]
end

subgraph group_operations["Commerce Operations"]
  node_orders["Order orchestration"]
  node_inventory["Inventory and warehouses<br/>[inventory.ts]"]
  node_fulfillment["Warehouse fulfillment<br/>[wms-fulfillment.ts]"]
  node_crm["CRM customers<br/>[crm.ts]"]
  node_purchasing["Purchasing and suppliers<br/>[purchasing.ts]"]
  node_dispatch["Dispatch<br/>[dispatch.ts]"]
end

subgraph group_finance["Finance and Insights"]
  node_payments["Payments<br/>[payments.ts]"]
  node_invoices["Invoices<br/>[invoices.ts]"]
  node_ledger["Accounting ledger<br/>[operations-gl.ts]"]
  node_analytics["Analytics engine<br/>[stats.ts]"]
end

subgraph group_celestial["Celestial Assistant"]
  node_celestial_orch["Assistant orchestration<br/>[orchestrator.ts]"]
  node_celestial_llm["LLM providers and streaming<br/>[llm.ts]"]
end

node_user(("Business user"))
node_llm_service{{"External language model"}}

node_user -->|"uses"| node_client_app
node_client_app -->|"renders routes"| node_client_routes
node_client_routes -->|"routes to"| node_shop_pages
node_client_routes -->|"routes to"| node_admin_pages
node_client_routes -->|"routes to"| node_mobile_pages
node_client_app -.->|"same-origin API"| node_api_router
node_api_router -->|"dispatches ERP requests"| node_native_router
node_api_router -->|"calls authentication"| node_auth
node_api_router -->|"loads auth profile"| node_customer_context
node_api_router -->|"checks session"| node_session
node_api_router -->|"runs analytics"| node_analytics
node_native_router -->|"checks roles"| node_session
node_native_router -->|"routes warehouse calls"| node_inventory
node_native_router -->|"routes customer calls"| node_crm
node_native_router -->|"routes supplier calls"| node_purchasing
node_native_router -->|"routes dispatch calls"| node_dispatch
node_native_router -->|"routes order operations"| node_orders
node_native_router -->|"routes fulfillment calls"| node_fulfillment
node_native_router -->|"routes payment calls"| node_payments
node_native_router -->|"routes invoice calls"| node_invoices
node_orders -->|"creates fulfillment task"| node_fulfillment
node_orders -->|"captures payment"| node_payments
node_orders -->|"issues invoice"| node_invoices
node_orders -->|"posts COGS"| node_ledger
node_fulfillment -->|"resolves pick bins"| node_inventory
node_customer_context -->|"finds buyer"| node_crm
node_auth -->|"reads and writes"| node_database
node_orders -->|"persists order state"| node_database
node_inventory -.->|"persists inventory"| node_database
node_api_router -.->|"routes assistant requests"| node_celestial_orch
node_celestial_orch -->|"completes chat"| node_celestial_llm
node_celestial_llm -->|"streams prompts"| node_llm_service

click node_client_app "https://github.com/nitinbollam/cosmos/blob/main/apps/client/src/App.tsx"
click node_client_routes "https://github.com/nitinbollam/cosmos/blob/main/apps/client/src/router.tsx"
click node_shop_pages "https://github.com/nitinbollam/cosmos/blob/main/apps/client/src/pages/catalog/page.tsx"
click node_admin_pages "https://github.com/nitinbollam/cosmos/tree/main/apps/client/src/pages/admin"
click node_mobile_pages "https://github.com/nitinbollam/cosmos/tree/main/apps/client/src/pages/m"
click node_api_router "https://github.com/nitinbollam/cosmos/blob/main/apps/web/server/api-router.ts"
click node_native_router "https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/native-router.ts"
click node_session "https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/session.ts"
click node_auth "https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/auth.ts"
click node_customer_context "https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/buyer-context.ts"
click node_orders "https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/order-orchestration.ts"
click node_inventory "https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/inventory.ts"
click node_fulfillment "https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/wms-fulfillment.ts"
click node_crm "https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/crm.ts"
click node_purchasing "https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/purchasing.ts"
click node_dispatch "https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/dispatch.ts"
click node_payments "https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/payments.ts"
click node_invoices "https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/invoices.ts"
click node_ledger "https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/operations-gl.ts"
click node_analytics "https://github.com/nitinbollam/cosmos/blob/main/packages/analytics-engine/src/stats.ts"
click node_celestial_orch "https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/celestial/orchestrator.ts"
click node_celestial_llm "https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/celestial/llm.ts"
click node_database "https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/db.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_client_app,node_client_routes,node_shop_pages,node_admin_pages,node_mobile_pages,node_user toneBlue
class node_api_router,node_native_router,node_session,node_auth,node_customer_context,node_database toneAmber
class node_orders,node_inventory,node_fulfillment,node_crm,node_purchasing,node_dispatch toneMint
class node_payments,node_invoices,node_ledger,node_analytics toneRose
class node_celestial_orch,node_celestial_llm,node_llm_service toneIndigo
```

## Components

### Client Experience

- [Client application](https://github.com/nitinbollam/cosmos/blob/main/apps/client/src/App.tsx): `apps/client/src/App.tsx`
- [Shop, admin, mobile routes](https://github.com/nitinbollam/cosmos/blob/main/apps/client/src/router.tsx): `apps/client/src/router.tsx`
- [Storefront and buyer portal](https://github.com/nitinbollam/cosmos/blob/main/apps/client/src/pages/catalog/page.tsx): `apps/client/src/pages/catalog/page.tsx`
- [ERP administration](https://github.com/nitinbollam/cosmos/tree/main/apps/client/src/pages/admin): `apps/client/src/pages/admin`
- [Mobile operations](https://github.com/nitinbollam/cosmos/tree/main/apps/client/src/pages/m): `apps/client/src/pages/m`

### API and Identity

- [HTTP API router](https://github.com/nitinbollam/cosmos/blob/main/apps/web/server/api-router.ts): `apps/web/server/api-router.ts`
- [ERP API routes](https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/native-router.ts): `apps/web/lib/server/native-router.ts`
- [Session and access control](https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/session.ts): `apps/web/lib/server/session.ts`
- [Authentication and signup](https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/auth.ts): `apps/web/lib/server/auth.ts`
- [Buyer context](https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/buyer-context.ts): `apps/web/lib/server/buyer-context.ts`
- [Prisma data stores](https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/db.ts): `apps/web/lib/server/db.ts`

### Commerce Operations

- [Order orchestration](https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/order-orchestration.ts): `apps/web/lib/server/order-orchestration.ts`
- [Inventory and warehouses](https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/inventory.ts): `apps/web/lib/server/inventory.ts`
- [Warehouse fulfillment](https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/wms-fulfillment.ts): `apps/web/lib/server/wms-fulfillment.ts`
- [CRM customers](https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/crm.ts): `apps/web/lib/server/crm.ts`
- [Purchasing and suppliers](https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/purchasing.ts): `apps/web/lib/server/purchasing.ts`
- [Dispatch](https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/dispatch.ts): `apps/web/lib/server/dispatch.ts`

### Finance and Insights

- [Payments](https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/payments.ts): `apps/web/lib/server/payments.ts`
- [Invoices](https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/invoices.ts): `apps/web/lib/server/invoices.ts`
- [Accounting ledger](https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/operations-gl.ts): `apps/web/lib/server/operations-gl.ts`
- [Analytics engine](https://github.com/nitinbollam/cosmos/blob/main/packages/analytics-engine/src/stats.ts): `packages/analytics-engine/src/stats.ts`

### Celestial Assistant

- [Assistant orchestration](https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/celestial/orchestrator.ts): `apps/web/lib/server/celestial/orchestrator.ts`
- [LLM providers and streaming](https://github.com/nitinbollam/cosmos/blob/main/apps/web/lib/server/celestial/llm.ts): `apps/web/lib/server/celestial/llm.ts`

### Other components

- **Business user**
- **External language model**

## Connections

- Business user → Client application: uses
- Client application → Shop, admin, mobile routes: renders routes (evidence: `apps/client/src/App.tsx`)
- Shop, admin, mobile routes → Storefront and buyer portal: routes to (evidence: `apps/client/src/router.tsx`)
- Shop, admin, mobile routes → ERP administration: routes to (evidence: `apps/client/src/router.tsx`)
- Shop, admin, mobile routes → Mobile operations: routes to (evidence: `apps/client/src/router.tsx`)
- Client application → HTTP API router: same-origin API
- HTTP API router → ERP API routes: dispatches ERP requests (evidence: `apps/web/server/api-router.ts`)
- HTTP API router → Authentication and signup: calls authentication (evidence: `apps/web/server/api-router.ts`)
- HTTP API router → Buyer context: loads auth profile (evidence: `apps/web/server/api-router.ts`)
- HTTP API router → Session and access control: checks session (evidence: `apps/web/server/api-router.ts`)
- HTTP API router → Analytics engine: runs analytics (evidence: `apps/web/server/api-router.ts`)
- ERP API routes → Session and access control: checks roles (evidence: `apps/web/lib/server/native-router.ts`)
- ERP API routes → Inventory and warehouses: routes warehouse calls (evidence: `apps/web/lib/server/native-router.ts`)
- ERP API routes → CRM customers: routes customer calls (evidence: `apps/web/lib/server/native-router.ts`)
- ERP API routes → Purchasing and suppliers: routes supplier calls (evidence: `apps/web/lib/server/native-router.ts`)
- ERP API routes → Dispatch: routes dispatch calls (evidence: `apps/web/lib/server/native-router.ts`)
- ERP API routes → Order orchestration: routes order operations (evidence: `apps/web/lib/server/native-router.ts`)
- ERP API routes → Warehouse fulfillment: routes fulfillment calls (evidence: `apps/web/lib/server/native-router.ts`)
- ERP API routes → Payments: routes payment calls (evidence: `apps/web/lib/server/native-router.ts`)
- ERP API routes → Invoices: routes invoice calls (evidence: `apps/web/lib/server/native-router.ts`)
- Order orchestration → Warehouse fulfillment: creates fulfillment task (evidence: `apps/web/lib/server/order-orchestration.ts`)
- Order orchestration → Payments: captures payment (evidence: `apps/web/lib/server/order-orchestration.ts`)
- Order orchestration → Invoices: issues invoice (evidence: `apps/web/lib/server/order-orchestration.ts`)
- Order orchestration → Accounting ledger: posts COGS (evidence: `apps/web/lib/server/order-orchestration.ts`)
- Warehouse fulfillment → Inventory and warehouses: resolves pick bins (evidence: `apps/web/lib/server/wms-fulfillment.ts`)
- Buyer context → CRM customers: finds buyer (evidence: `apps/web/lib/server/buyer-context.ts`)
- Authentication and signup → Prisma data stores: reads and writes (evidence: `apps/web/lib/server/auth.ts`)
- Order orchestration → Prisma data stores: persists order state (evidence: `apps/web/lib/server/order-orchestration.ts`)
- Inventory and warehouses → Prisma data stores: persists inventory
- HTTP API router → Assistant orchestration: routes assistant requests
- Assistant orchestration → LLM providers and streaming: completes chat (evidence: `apps/web/lib/server/celestial/orchestrator.ts`)
- LLM providers and streaming → External language model: streams prompts (evidence: `apps/web/lib/server/celestial/llm.ts`)
