# ever-co/ever-demand architecture

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

- Interactive diagram: https://gitdiagram.com/ever-co/ever-demand
- Repository: https://github.com/ever-co/ever-demand

## Overview

#### 1. Purpose and topology
Ever Demand is a TypeScript monorepo for a headless, real-time commerce and delivery platform: multi-store marketplaces, inventory/catalogs, ordering, merchant operations, carrier dispatch/tracking, and administration. Lerna/workspaces coordinate independently deployable API and client packages.
- `package.json`
- `lerna.json`
- `package.workspaces.json`

#### 2. Backend API entry and composition
The central Node.js/NestJS API boots from `packages/core/src/main.ts`, composes modules in `packages/core/src/app.module.ts`, and has PM2 bootstrap support. It exposes GraphQL as the principal domain surface, with REST controllers and custom IO/WebSocket infrastructure also present.
- `packages/core/src/main.ts`
- `packages/core/src/app.module.ts`
- `packages/core/src/@pyro/io/routers-manager.ts`

#### 3. Domain model and persistence boundary
`packages/common` defines shared entities, interfaces, enums, and router contracts consumed by server and TypeScript clients. The active persistence design is MongoDB/Mongoose, abstracted through the Pyro DB object/model layer and server-side entity services. Core business aggregates include users/admins, warehouses, products/categories/promotions, orders/order products, carriers, locations, invitations, devices, and payment gateways.
- `packages/common/src/entities/index.ts`
- `packages/common/src/@pyro/db/model.ts`
- `packages/core/src/@pyro/db-server/entity-service.ts`

#### 4. Commerce, fulfillment, and realtime flows
Clients query/mutate domain GraphQL modules; resolvers delegate to services, which persist entities and publish updates through subscription infrastructure. The main operational chain is product/warehouse availability → customer order → warehouse order processing → carrier assignment/delivery status and geo-location tracking. Auth is JWT-based and protects server/client routes.
- `packages/core/src/graphql/orders/order.resolver.ts`
- `packages/core/src/services/orders/OrdersService.ts`
- `packages/core/src/services/warehouses/WarehousesOrdersService.ts`
- `packages/core/src/graphql/subscriptions/subscriptions.service.ts`
- `packages/core/src/auth/jwt.strategy.ts`

#### 5. Administrative control plane
The Angular admin SPA is the management interface for dashboards, users/customers, products, warehouses, orders, carriers, settings, invitations, and simulation/fake data. Its app routing/module boundary is backed by data services that call the API; admin authentication and role access are explicit core boundaries.
- `packages/admin-web-angular/src/main.ts`
- `packages/admin-web-angular/src/app/app.module.ts`
- `packages/admin-web-angular/src/app/@core/auth/admin-auth.guard.ts`
- `packages/admin-web-angular/src/app/@core/data/data.service.ts`

#### 6. Actor-facing applications
Separate clients implement role-specific workflows against the shared API: merchant tablet manages store inventory, orders, promotions, customers, and carriers; carrier Ionic app handles delivery execution, pickup/return, and location; customer storefronts support merchant discovery, products, checkout/orders, and tracking. Multiple customer implementations coexist: Angular/Ionic, React Native Expo, Flutter, and Gatsby.
- `packages/merchant-tablet-ionic/src/app/app.module.ts`
- `packages/carrier-mobile-ionic/src/services/geo-location.service.ts`
- `packages/shop-mobile-ionic/src/app/services/orders/orders.service.ts`
- `packages/shop-mobile-expo/src/client/orders/mutations.ts`
- `packages/shop-web-gatsby/src/apollo/client.tsx`

#### 7. Shared client transport and cross-cutting capabilities
`common-angular` provides typed router services, request/response abstractions, sockets, Google Maps loading, locale/product localization, and maintenance/server-connection checks. This is the principal frontend integration boundary rather than direct database access. Internationalization assets exist across applications; maps/geolocation and payment integrations are client-visible capabilities.
- `packages/common-angular/src/lib/router/router.service.ts`
- `packages/common-angular/src/lib/socket.service.ts`
- `packages/common-angular/src/services/googleMapsLoader.ts`
- `packages/shop-mobile-ionic/src/app/services/stripeLoader.ts`

#### 8. Runtime and deployment
Production topology is container-oriented: Docker Compose can run the platform locally, per-app Docker/Nginx assets serve browser clients, and Kubernetes manifests support cluster deployment. MongoDB is the default external datastore; PM2 is supported for production process management. CI/CD definitions include CircleCI, GitHub Docker publishing/deployment workflows, and Kubernetes deployment assets.
- `docker-compose.yml`
- `.deploy/api/Dockerfile`
- `.deploy/k8s/k8s-manifest.demo.yaml`
- `.github/workflows/docker-build-publish.yml`

Main entry points: [`packages/common-angular/src/lib/router/router.service.ts`](https://github.com/ever-co/ever-demand/blob/develop/packages/common-angular/src/lib/router/router.service.ts) (Common Angular Transport), [`packages/core/src/services/orders/OrdersService.ts`](https://github.com/ever-co/ever-demand/blob/develop/packages/core/src/services/orders/OrdersService.ts) (Order Services), [`packages/core/src/graphql/orders/order.resolver.ts`](https://github.com/ever-co/ever-demand/blob/develop/packages/core/src/graphql/orders/order.resolver.ts) (GraphQL Domain Surface), [`packages/core/src/@pyro/db-server/entity-service.ts`](https://github.com/ever-co/ever-demand/blob/develop/packages/core/src/%40pyro/db-server/entity-service.ts) (Entity Services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Actor Applications"]
  node_admin["Angular Admin SPA<br/>admin client<br/>[app.module.ts]"]
  node_merchant["Merchant Tablet<br/>merchant client<br/>[app.module.ts]"]
  node_carrier["Carrier Mobile<br/>carrier client"]
  node_customer["Customer Storefronts<br/>customer clients<br/>[orders.service.ts]"]
end

subgraph group_api["Core API"]
  node_bootstrap["NestJS Bootstrap<br/>API entrypoint<br/>[main.ts]"]
  node_app_module["Application Modules<br/>NestJS composition<br/>[app.module.ts]"]
  node_graphql{{"GraphQL Domain Surface<br/>GraphQL resolvers<br/>[order.resolver.ts]"}}
  node_auth["JWT Authentication<br/>auth boundary<br/>[jwt.strategy.ts]"]
  node_orders["Order Services<br/>commerce service<br/>[OrdersService.ts]"]
  node_warehouse["Warehouse Processing<br/>fulfillment service"]
  node_realtime["Subscriptions &amp; IO<br/>realtime infrastructure"]
  node_entity_service["Entity Services<br/>persistence service<br/>[entity-service.ts]"]
end

subgraph group_shared["Shared Libraries"]
  node_common_angular["Common Angular Transport<br/>client SDK<br/>[router.service.ts]"]
  node_common["Shared Domain Contracts<br/>shared library<br/>[index.ts]"]
  node_model["Pyro DB Models<br/>model abstraction<br/>[model.ts]"]
end

subgraph group_runtime["Runtime &amp; Delivery"]
  node_mongo[("MongoDB<br/>datastore")]
  node_compose["Docker Compose<br/>local runtime<br/>[docker-compose.yml]"]
  node_api_image["API Container Image<br/>container build<br/>[Dockerfile]"]
  node_kubernetes["Kubernetes Deployment<br/>cluster deployment"]
  node_ci["Docker Publish CI<br/>CI/CD workflow"]
end

node_admin -->|"uses"| node_common_angular
node_merchant -->|"uses"| node_common_angular
node_carrier -->|"uses transport"| node_common_angular
node_customer -->|"uses transport"| node_common_angular
node_common_angular -->|"API requests"| node_graphql
node_common_angular -->|"socket updates"| node_realtime
node_bootstrap -->|"boots"| node_app_module
node_app_module -->|"mounts"| node_graphql
node_graphql -->|"authenticates"| node_auth
node_graphql -->|"delegates orders"| node_orders
node_orders -->|"fulfillment workflow"| node_warehouse
node_orders -->|"persists"| node_entity_service
node_warehouse -->|"updates fulfillment"| node_entity_service
node_orders -->|"publishes updates"| node_realtime
node_warehouse -->|"publishes status"| node_realtime
node_entity_service -->|"uses models"| node_model
node_model -->|"models shared entities"| node_common
node_entity_service -->|"reads and writes"| node_mongo
node_compose -->|"runs"| node_api_image
node_ci -->|"builds and publishes"| node_api_image
node_api_image -->|"deployed by"| node_kubernetes
node_kubernetes -->|"runs API"| node_bootstrap

click node_admin "https://github.com/ever-co/ever-demand/blob/develop/packages/admin-web-angular/src/app/app.module.ts"
click node_merchant "https://github.com/ever-co/ever-demand/blob/develop/packages/merchant-tablet-ionic/src/app/app.module.ts"
click node_carrier "https://github.com/ever-co/ever-demand/blob/develop/packages/carrier-mobile-ionic/src/services/geo-location.service.ts"
click node_customer "https://github.com/ever-co/ever-demand/blob/develop/packages/shop-mobile-ionic/src/app/services/orders/orders.service.ts"
click node_common_angular "https://github.com/ever-co/ever-demand/blob/develop/packages/common-angular/src/lib/router/router.service.ts"
click node_common "https://github.com/ever-co/ever-demand/blob/develop/packages/common/src/entities/index.ts"
click node_bootstrap "https://github.com/ever-co/ever-demand/blob/develop/packages/core/src/main.ts"
click node_app_module "https://github.com/ever-co/ever-demand/blob/develop/packages/core/src/app.module.ts"
click node_graphql "https://github.com/ever-co/ever-demand/blob/develop/packages/core/src/graphql/orders/order.resolver.ts"
click node_auth "https://github.com/ever-co/ever-demand/blob/develop/packages/core/src/auth/jwt.strategy.ts"
click node_orders "https://github.com/ever-co/ever-demand/blob/develop/packages/core/src/services/orders/OrdersService.ts"
click node_warehouse "https://github.com/ever-co/ever-demand/blob/develop/packages/core/src/services/warehouses/WarehousesOrdersService.ts"
click node_realtime "https://github.com/ever-co/ever-demand/blob/develop/packages/core/src/graphql/subscriptions/subscriptions.service.ts"
click node_entity_service "https://github.com/ever-co/ever-demand/blob/develop/packages/core/src/%40pyro/db-server/entity-service.ts"
click node_model "https://github.com/ever-co/ever-demand/blob/develop/packages/common/src/%40pyro/db/model.ts"
click node_compose "https://github.com/ever-co/ever-demand/blob/develop/docker-compose.yml"
click node_api_image "https://github.com/ever-co/ever-demand/blob/develop/.deploy/api/Dockerfile"
click node_kubernetes "https://github.com/ever-co/ever-demand/blob/develop/.deploy/k8s/k8s-manifest.demo.yaml"
click node_ci "https://github.com/ever-co/ever-demand/blob/develop/.github/workflows/docker-build-publish.yml"

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_admin,node_merchant,node_carrier,node_customer toneBlue
class node_bootstrap,node_app_module,node_graphql,node_auth,node_orders,node_warehouse,node_realtime,node_entity_service toneAmber
class node_common_angular,node_common,node_model toneMint
class node_mongo,node_compose,node_api_image,node_kubernetes,node_ci toneRose
```

## Components

### Actor Applications

Role-specific clients consume the shared API.

- [Angular Admin SPA](https://github.com/ever-co/ever-demand/blob/develop/packages/admin-web-angular/src/app/app.module.ts): admin client · Management UI with authenticated role access. · `packages/admin-web-angular/src/app/app.module.ts`
- [Merchant Tablet](https://github.com/ever-co/ever-demand/blob/develop/packages/merchant-tablet-ionic/src/app/app.module.ts): merchant client · Inventory, order, promotion, and carrier operations. · `packages/merchant-tablet-ionic/src/app/app.module.ts`
- [Carrier Mobile](https://github.com/ever-co/ever-demand/blob/develop/packages/carrier-mobile-ionic/src/services/geo-location.service.ts): carrier client · Delivery execution and location reporting. · `packages/carrier-mobile-ionic/src/services/geo-location.service.ts`
- [Customer Storefronts](https://github.com/ever-co/ever-demand/blob/develop/packages/shop-mobile-ionic/src/app/services/orders/orders.service.ts): customer clients · Ionic, Expo, Flutter, and Gatsby shopping experiences. · `packages/shop-mobile-ionic/src/app/services/orders/orders.service.ts`

### Core API

NestJS domain, auth, persistence, and realtime layers.

- [NestJS Bootstrap](https://github.com/ever-co/ever-demand/blob/develop/packages/core/src/main.ts): API entrypoint · Starts the core Node.js API runtime. · `packages/core/src/main.ts`
- [Application Modules](https://github.com/ever-co/ever-demand/blob/develop/packages/core/src/app.module.ts): NestJS composition · Composes API modules and domain capabilities. · `packages/core/src/app.module.ts`
- [GraphQL Domain Surface](https://github.com/ever-co/ever-demand/blob/develop/packages/core/src/graphql/orders/order.resolver.ts): GraphQL resolvers · Primary query and mutation boundary. · `packages/core/src/graphql/orders/order.resolver.ts`
- [JWT Authentication](https://github.com/ever-co/ever-demand/blob/develop/packages/core/src/auth/jwt.strategy.ts): auth boundary · Protects API and client routes. · `packages/core/src/auth/jwt.strategy.ts`
- [Order Services](https://github.com/ever-co/ever-demand/blob/develop/packages/core/src/services/orders/OrdersService.ts): commerce service · Coordinates customer order business logic. · `packages/core/src/services/orders/OrdersService.ts`
- [Warehouse Processing](https://github.com/ever-co/ever-demand/blob/develop/packages/core/src/services/warehouses/WarehousesOrdersService.ts): fulfillment service · Processes warehouse-side order fulfillment. · `packages/core/src/services/warehouses/WarehousesOrdersService.ts`
- [Subscriptions & IO](https://github.com/ever-co/ever-demand/blob/develop/packages/core/src/graphql/subscriptions/subscriptions.service.ts): realtime infrastructure · Publishes domain updates over subscriptions and sockets. · `packages/core/src/graphql/subscriptions/subscriptions.service.ts`
- [Entity Services](https://github.com/ever-co/ever-demand/blob/develop/packages/core/src/%40pyro/db-server/entity-service.ts): persistence service · Server-side entity access layer. · `packages/core/src/@pyro/db-server/entity-service.ts`

### Shared Libraries

Contracts and client transport shared across packages.

- [Common Angular Transport](https://github.com/ever-co/ever-demand/blob/develop/packages/common-angular/src/lib/router/router.service.ts): client SDK · Typed routers, sockets, maps, locale, and connection services. · `packages/common-angular/src/lib/router/router.service.ts`
- [Shared Domain Contracts](https://github.com/ever-co/ever-demand/blob/develop/packages/common/src/entities/index.ts): shared library · Entities, interfaces, enums, and router contracts. · `packages/common/src/entities/index.ts`
- [Pyro DB Models](https://github.com/ever-co/ever-demand/blob/develop/packages/common/src/%40pyro/db/model.ts): model abstraction · Shared object and model layer over persistence. · `packages/common/src/@pyro/db/model.ts`

### Runtime & Delivery

Container, cluster, and process deployment topology.

- **MongoDB**: datastore · Default operational datastore.
- [Docker Compose](https://github.com/ever-co/ever-demand/blob/develop/docker-compose.yml): local runtime · Runs the platform container topology locally. · `docker-compose.yml`
- [API Container Image](https://github.com/ever-co/ever-demand/blob/develop/.deploy/api/Dockerfile): container build · Production API image definition. · `.deploy/api/Dockerfile`
- [Kubernetes Deployment](https://github.com/ever-co/ever-demand/blob/develop/.deploy/k8s/k8s-manifest.demo.yaml): cluster deployment · Cluster manifest for deployed platform services. · `.deploy/k8s/k8s-manifest.demo.yaml`
- [Docker Publish CI](https://github.com/ever-co/ever-demand/blob/develop/.github/workflows/docker-build-publish.yml): CI/CD workflow · Builds and publishes deployment images. · `.github/workflows/docker-build-publish.yml`

## Connections

- Angular Admin SPA → Common Angular Transport: uses
- Merchant Tablet → Common Angular Transport: uses
- Carrier Mobile → Common Angular Transport: uses transport
- Customer Storefronts → Common Angular Transport: uses transport
- Common Angular Transport → GraphQL Domain Surface: API requests
- Common Angular Transport → Subscriptions & IO: socket updates
- NestJS Bootstrap → Application Modules: boots
- Application Modules → GraphQL Domain Surface: mounts
- GraphQL Domain Surface → JWT Authentication: authenticates
- GraphQL Domain Surface → Order Services: delegates orders
- Order Services → Warehouse Processing: fulfillment workflow
- Order Services → Entity Services: persists
- Warehouse Processing → Entity Services: updates fulfillment
- Order Services → Subscriptions & IO: publishes updates
- Warehouse Processing → Subscriptions & IO: publishes status
- Entity Services → Pyro DB Models: uses models
- Pyro DB Models → Shared Domain Contracts: models shared entities
- Entity Services → MongoDB: reads and writes
- Docker Compose → API Container Image: runs
- Docker Publish CI → API Container Image: builds and publishes
- API Container Image → Kubernetes Deployment: deployed by
- Kubernetes Deployment → NestJS Bootstrap: runs API