# atqatq/sentinel architecture

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

## Overview

Sentinel is a multi-tenant supply-chain planning, sourcing, and intelligence layer over Precoro: it ingests file drops, produces plans and proposals, governs approvals, then reconciles and measures execution without writing back to Precoro. The graph preserves the README’s major capabilities and documented architecture. Some subsystem links are based on README-level descriptions because their runtime sources were not sampled; uncertain wiring is omitted.

Main entry points: [`packages/db/index.js`](https://github.com/atqatq/sentinel/blob/main/packages/db/index.js) (Tenant Data Store), [`packages/procure-service/src/cf-api.js`](https://github.com/atqatq/sentinel/blob/main/packages/procure-service/src/cf-api.js) (CF Decision Gate), [`packages/core/modules/auth/src/login.js`](https://github.com/atqatq/sentinel/blob/main/packages/core/modules/auth/src/login.js) (Authentication), [`packages/ingest-service/src/worker.js`](https://github.com/atqatq/sentinel/blob/main/packages/ingest-service/src/worker.js) (File-to-Rows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["File Ingestion"]
  node_worker["Ingestion Worker<br/>[main.js]"]
  node_ingest_service["File-to-Rows<br/>[worker.js]"]
  node_ingestion_core["Ingestion Rules<br/>[parse.js]"]
  node_ingest_db["Ingestion Adapter"]
end

subgraph group_planning["Planning"]
  node_plan_service["Plan Run Boundary<br/>[handler.js]"]
  node_engine["MRP Engine<br/>[engine.js]"]
  node_calendar["Calendar Rules<br/>[calendar.js]"]
end

subgraph group_governance["Governance And Feedback"]
  node_feedback["Execution Feedback<br/>[feedback.js]"]
  node_sourcing["Supplier Scorecards"]
  node_procure_service["CF Decision Gate<br/>[cf-api.js]"]
  node_approval["Approval Controls<br/>[decide.js]"]
  node_ledger["Append-only Ledger<br/>[records.js]"]
end

subgraph group_operations["Operations And Intelligence"]
  node_ops["Freshness And Health<br/>[datahealth.js]"]
  node_intelligence["Intelligence Policy<br/>[policy.js]"]
  node_kpi["KPI Catalog<br/>[catalog.js]"]
  node_dr["Restore Rehearsal<br/>[rehearsal.js]"]
end

subgraph group_surface["User Surface"]
  node_plan_api["Plan API<br/>[route.ts]"]
  node_approval_api["CF Approval API<br/>[route.ts]"]
  node_auth["Authentication<br/>[login.js]"]
  node_health_api["Data-health API<br/>[route.ts]"]
  node_setup["Tenant Setup<br/>[steps.js]"]
  node_web["Web Application<br/>[page.tsx]"]
end

node_source(("Precoro Exports"))
node_store[("Tenant Data Store<br/>[index.js]")]

node_source -->|"supplies files"| node_worker
node_worker -->|"processes claims"| node_ingest_service
node_ingest_service -->|"parses and normalizes"| node_ingestion_core
node_ingest_service -->|"persists rows"| node_ingest_db
node_ingest_db -->|"reads and writes"| node_store
node_plan_api -->|"resolves session"| node_auth
node_plan_api -->|"runs plan"| node_plan_service
node_plan_service -->|"computes plan"| node_engine
node_plan_service -->|"reads and seals"| node_store
node_engine -->|"uses calendar basis"| node_calendar
node_feedback -->|"records realized facts"| node_store
node_sourcing -->|"reads scorecard data"| node_store
node_approval_api -->|"resolves session"| node_auth
node_approval_api -->|"submits decision"| node_procure_service
node_procure_service -->|"evaluates decision"| node_approval
node_procure_service -->|"records decision"| node_ledger
node_procure_service -->|"reads and updates"| node_store
node_health_api -->|"resolves session"| node_auth
node_health_api -->|"reads health facts"| node_ops
node_ops -->|"derives from records"| node_store
node_intelligence -.->|"governs reports"| node_web
node_kpi -->|"defines KPI surface"| node_web
node_dr -.->|"evaluates restore state"| node_store
node_setup -->|"guides tenant setup"| node_store
node_auth -->|"reads credentials and sessions"| node_store

click node_worker "https://github.com/atqatq/sentinel/blob/main/apps/worker/src/main.js"
click node_ingest_service "https://github.com/atqatq/sentinel/blob/main/packages/ingest-service/src/worker.js"
click node_ingestion_core "https://github.com/atqatq/sentinel/blob/main/packages/core/modules/ingestion/src/parse.js"
click node_ingest_db "https://github.com/atqatq/sentinel/blob/main/packages/db/ingest-worker-adapter.js"
click node_store "https://github.com/atqatq/sentinel/blob/main/packages/db/index.js"
click node_plan_api "https://github.com/atqatq/sentinel/blob/main/apps/web/src/app/api/plan/route.ts"
click node_plan_service "https://github.com/atqatq/sentinel/blob/main/packages/plan-service/src/handler.js"
click node_engine "https://github.com/atqatq/sentinel/blob/main/packages/core/modules/planning-engine/src/engine.js"
click node_calendar "https://github.com/atqatq/sentinel/blob/main/packages/core/modules/calendar/src/calendar.js"
click node_feedback "https://github.com/atqatq/sentinel/blob/main/packages/core/modules/execution-feedback/src/feedback.js"
click node_sourcing "https://github.com/atqatq/sentinel/blob/main/packages/db/scorecard-adapter.js"
click node_approval_api "https://github.com/atqatq/sentinel/blob/main/apps/web/src/app/api/approvals/cf/route.ts"
click node_procure_service "https://github.com/atqatq/sentinel/blob/main/packages/procure-service/src/cf-api.js"
click node_approval "https://github.com/atqatq/sentinel/blob/main/packages/core/modules/approval/src/decide.js"
click node_ledger "https://github.com/atqatq/sentinel/blob/main/packages/core/modules/ledger/src/records.js"
click node_auth "https://github.com/atqatq/sentinel/blob/main/packages/core/modules/auth/src/login.js"
click node_health_api "https://github.com/atqatq/sentinel/blob/main/apps/web/src/app/api/data-health/route.ts"
click node_ops "https://github.com/atqatq/sentinel/blob/main/packages/core/modules/ops/src/datahealth.js"
click node_intelligence "https://github.com/atqatq/sentinel/blob/main/packages/core/modules/intelligence/src/policy.js"
click node_kpi "https://github.com/atqatq/sentinel/blob/main/packages/core/modules/kpi-catalog/src/catalog.js"
click node_dr "https://github.com/atqatq/sentinel/blob/main/packages/core/modules/dr/src/rehearsal.js"
click node_setup "https://github.com/atqatq/sentinel/blob/main/packages/core/modules/setup/src/steps.js"
click node_web "https://github.com/atqatq/sentinel/blob/main/apps/web/src/app/page.tsx"

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_worker,node_ingest_service,node_ingestion_core,node_ingest_db toneBlue
class node_plan_service,node_engine,node_calendar,node_store toneAmber
class node_feedback,node_sourcing,node_procure_service,node_approval,node_ledger toneMint
class node_ops,node_intelligence,node_kpi,node_dr toneRose
class node_plan_api,node_approval_api,node_auth,node_health_api,node_setup,node_web,node_source toneIndigo
```

## Components

### File Ingestion

- [Ingestion Worker](https://github.com/atqatq/sentinel/blob/main/apps/worker/src/main.js): `apps/worker/src/main.js`
- [File-to-Rows](https://github.com/atqatq/sentinel/blob/main/packages/ingest-service/src/worker.js): `packages/ingest-service/src/worker.js`
- [Ingestion Rules](https://github.com/atqatq/sentinel/blob/main/packages/core/modules/ingestion/src/parse.js): `packages/core/modules/ingestion/src/parse.js`
- [Ingestion Adapter](https://github.com/atqatq/sentinel/blob/main/packages/db/ingest-worker-adapter.js): `packages/db/ingest-worker-adapter.js`

### Planning

- [Plan Run Boundary](https://github.com/atqatq/sentinel/blob/main/packages/plan-service/src/handler.js): `packages/plan-service/src/handler.js`
- [MRP Engine](https://github.com/atqatq/sentinel/blob/main/packages/core/modules/planning-engine/src/engine.js): `packages/core/modules/planning-engine/src/engine.js`
- [Calendar Rules](https://github.com/atqatq/sentinel/blob/main/packages/core/modules/calendar/src/calendar.js): `packages/core/modules/calendar/src/calendar.js`

### Governance And Feedback

- [Execution Feedback](https://github.com/atqatq/sentinel/blob/main/packages/core/modules/execution-feedback/src/feedback.js): `packages/core/modules/execution-feedback/src/feedback.js`
- [Supplier Scorecards](https://github.com/atqatq/sentinel/blob/main/packages/db/scorecard-adapter.js): `packages/db/scorecard-adapter.js`
- [CF Decision Gate](https://github.com/atqatq/sentinel/blob/main/packages/procure-service/src/cf-api.js): `packages/procure-service/src/cf-api.js`
- [Approval Controls](https://github.com/atqatq/sentinel/blob/main/packages/core/modules/approval/src/decide.js): `packages/core/modules/approval/src/decide.js`
- [Append-only Ledger](https://github.com/atqatq/sentinel/blob/main/packages/core/modules/ledger/src/records.js): `packages/core/modules/ledger/src/records.js`

### Operations And Intelligence

- [Freshness And Health](https://github.com/atqatq/sentinel/blob/main/packages/core/modules/ops/src/datahealth.js): `packages/core/modules/ops/src/datahealth.js`
- [Intelligence Policy](https://github.com/atqatq/sentinel/blob/main/packages/core/modules/intelligence/src/policy.js): `packages/core/modules/intelligence/src/policy.js`
- [KPI Catalog](https://github.com/atqatq/sentinel/blob/main/packages/core/modules/kpi-catalog/src/catalog.js): `packages/core/modules/kpi-catalog/src/catalog.js`
- [Restore Rehearsal](https://github.com/atqatq/sentinel/blob/main/packages/core/modules/dr/src/rehearsal.js): `packages/core/modules/dr/src/rehearsal.js`

### User Surface

- [Plan API](https://github.com/atqatq/sentinel/blob/main/apps/web/src/app/api/plan/route.ts): `apps/web/src/app/api/plan/route.ts`
- [CF Approval API](https://github.com/atqatq/sentinel/blob/main/apps/web/src/app/api/approvals/cf/route.ts): `apps/web/src/app/api/approvals/cf/route.ts`
- [Authentication](https://github.com/atqatq/sentinel/blob/main/packages/core/modules/auth/src/login.js): `packages/core/modules/auth/src/login.js`
- [Data-health API](https://github.com/atqatq/sentinel/blob/main/apps/web/src/app/api/data-health/route.ts): `apps/web/src/app/api/data-health/route.ts`
- [Tenant Setup](https://github.com/atqatq/sentinel/blob/main/packages/core/modules/setup/src/steps.js): `packages/core/modules/setup/src/steps.js`
- [Web Application](https://github.com/atqatq/sentinel/blob/main/apps/web/src/app/page.tsx): `apps/web/src/app/page.tsx`

### Other components

- **Precoro Exports**
- [Tenant Data Store](https://github.com/atqatq/sentinel/blob/main/packages/db/index.js): `packages/db/index.js`

## Connections

- Precoro Exports → Ingestion Worker: supplies files
- Ingestion Worker → File-to-Rows: processes claims
- File-to-Rows → Ingestion Rules: parses and normalizes
- File-to-Rows → Ingestion Adapter: persists rows
- Ingestion Adapter → Tenant Data Store: reads and writes
- Plan API → Authentication: resolves session
- Plan API → Plan Run Boundary: runs plan
- Plan Run Boundary → MRP Engine: computes plan
- Plan Run Boundary → Tenant Data Store: reads and seals
- MRP Engine → Calendar Rules: uses calendar basis
- Execution Feedback → Tenant Data Store: records realized facts
- Supplier Scorecards → Tenant Data Store: reads scorecard data
- CF Approval API → Authentication: resolves session
- CF Approval API → CF Decision Gate: submits decision
- CF Decision Gate → Approval Controls: evaluates decision
- CF Decision Gate → Append-only Ledger: records decision
- CF Decision Gate → Tenant Data Store: reads and updates
- Data-health API → Authentication: resolves session
- Data-health API → Freshness And Health: reads health facts
- Freshness And Health → Tenant Data Store: derives from records
- Intelligence Policy → Web Application: governs reports
- KPI Catalog → Web Application: defines KPI surface
- Restore Rehearsal → Tenant Data Store: evaluates restore state
- Tenant Setup → Tenant Data Store: guides tenant setup
- Authentication → Tenant Data Store: reads credentials and sessions