# excelyynxl-a11y/fn-key architecture

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

- Interactive diagram: https://gitdiagram.com/excelyynxl-a11y/fn-key
- Repository: https://github.com/excelyynxl-a11y/fn-key

## Overview

SDOC is an explainable shipping-document verification system. Operators start asynchronous inbox runs, inspect classifications and SI/BL comparisons, resolve uncertain cases, manage learned knowledge, and validate or export results. The documented processing stages run from email classification through attachment parsing, document-role detection, field extraction, normalization, and deterministic comparison; selective AI fallback supports unresolved work. The README documents MongoDB persistence and the broad workflow, while sampled source confirms key UI requests, API routing, pipeline dependencies, and review handling; some subsystem links rely on README documentation because their implementations were not sampled.

Main entry points: [`server/src/services/pipelineService.js`](https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/services/pipelineService.js) (Email processing pipeline), [`server/src/services/reviewService.js`](https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/services/reviewService.js) (Review handling), [`server/src/services/runService.js`](https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/services/runService.js) (Run orchestration), [`server/src/controllers/runController.js`](https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/controllers/runController.js) (Run controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Operations dashboard"]
  node_dashboard_ui["Operations dashboard<br/>[LandingPage.jsx]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_api["API and workflow"]
  node_api_app["Express API<br/>[app.js]"]
  node_run_api["Run controller<br/>[runController.js]"]
  node_review_api["Review controller"]
  node_knowledge_api["Knowledge controller"]
  node_run_engine["Run orchestration<br/>[runService.js]"]
  node_dataset["Inbox dataset"]
end

subgraph group_verification["Verification pipeline"]
  node_pipeline["Email processing pipeline<br/>[pipelineService.js]"]
  node_classification["Adaptive classification"]
  node_attachment_parser["Attachment parsing"]
  node_document_roles["Document role detection"]
  node_field_extraction["Field extraction"]
  node_normalization["Field normalization"]
  node_comparison["Deterministic comparison"]
  node_ai_fallback["Structured AI fallback"]
end

subgraph group_review["Review and learning"]
  node_review_service["Review handling<br/>[reviewService.js]"]
  node_knowledge_service["Knowledge and learning"]
end

subgraph group_state["Persistence and outputs"]
  node_metrics["Run metrics<br/>[metricsService.js]"]
  node_submission["Submission export"]
  node_email_store[("Email results<br/>[Email.js]")]
  node_run_store[("Processing runs<br/>[ProcessingRun.js]")]
  node_review_store[("Review cases<br/>[ReviewCase.js]")]
  node_audit_store[("Audit history<br/>[AuditEvent.js]")]
end

node_operator(("Operations user"))
node_mongo[("MongoDB")]
node_openai["OpenAI API"]

node_operator -->|"operates"| node_dashboard_ui
node_dashboard_ui -->|"requests through"| node_api_client
node_api_client -->|"sends HTTP"| node_api_app
node_api_app -->|"routes runs"| node_run_api
node_api_app -->|"routes reviews"| node_review_api
node_api_app -->|"routes knowledge"| node_knowledge_api
node_run_api -->|"starts runs"| node_run_engine
node_run_engine -->|"loads dataset"| node_dataset
node_run_engine -->|"processes emails"| node_pipeline
node_pipeline -->|"classifies"| node_classification
node_pipeline -->|"parses attachments"| node_attachment_parser
node_pipeline -->|"identifies roles"| node_document_roles
node_pipeline -->|"extracts fields"| node_field_extraction
node_pipeline -->|"normalizes fields"| node_normalization
node_pipeline -->|"compares documents"| node_comparison
node_pipeline -->|"falls back to AI"| node_ai_fallback
node_ai_fallback -->|"requests structured output"| node_openai
node_run_engine -->|"persists results"| node_email_store
node_run_engine -->|"tracks run state"| node_run_store
node_run_engine -->|"routes exceptions"| node_review_service
node_review_api -->|"resolves and retries"| node_review_service
node_review_service -->|"reprocesses corrections"| node_pipeline
node_review_service -->|"updates cases"| node_review_store
node_review_service -->|"updates reviewed email"| node_email_store
node_review_service -->|"records decisions"| node_audit_store
node_review_service -->|"learns phrases"| node_knowledge_service
node_knowledge_api -->|"manages knowledge"| node_knowledge_service
node_run_api -->|"gets metrics"| node_metrics
node_run_api -->|"builds export"| node_submission
node_run_api -->|"reads results"| node_email_store
node_metrics -->|"reads email state"| node_email_store
node_metrics -->|"reads run state"| node_run_store
node_metrics -->|"reads review state"| node_review_store
node_email_store -->|"persists in"| node_mongo
node_run_store -->|"persists in"| node_mongo
node_review_store -->|"persists in"| node_mongo
node_audit_store -->|"persists in"| node_mongo

click node_dashboard_ui "https://github.com/excelyynxl-a11y/fn-key/blob/main/client/src/pages/LandingPage.jsx"
click node_api_client "https://github.com/excelyynxl-a11y/fn-key/blob/main/client/src/services/api.js"
click node_api_app "https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/app.js"
click node_run_api "https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/controllers/runController.js"
click node_review_api "https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/controllers/reviewController.js"
click node_knowledge_api "https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/controllers/knowledgeController.js"
click node_run_engine "https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/services/runService.js"
click node_dataset "https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/repositories/datasetRepository.js"
click node_pipeline "https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/services/pipelineService.js"
click node_classification "https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/services/adaptiveClassificationService.js"
click node_attachment_parser "https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/services/fileParserService.js"
click node_document_roles "https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/services/documentTypeService.js"
click node_field_extraction "https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/services/fieldExtractionService.js"
click node_normalization "https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/services/normalizationService.js"
click node_comparison "https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/services/comparisonService.js"
click node_ai_fallback "https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/services/documentAiService.js"
click node_review_service "https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/services/reviewService.js"
click node_knowledge_service "https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/services/knowledgeService.js"
click node_metrics "https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/services/metricsService.js"
click node_submission "https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/services/submissionService.js"
click node_email_store "https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/models/Email.js"
click node_run_store "https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/models/ProcessingRun.js"
click node_review_store "https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/models/ReviewCase.js"
click node_audit_store "https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/models/AuditEvent.js"

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_dashboard_ui,node_api_client,node_operator toneBlue
class node_api_app,node_run_api,node_review_api,node_knowledge_api,node_run_engine,node_dataset,node_mongo toneAmber
class node_pipeline,node_classification,node_attachment_parser,node_document_roles,node_field_extraction,node_normalization,node_comparison,node_ai_fallback,node_openai toneMint
class node_review_service,node_knowledge_service toneRose
class node_metrics,node_submission,node_email_store,node_run_store,node_review_store,node_audit_store toneIndigo
```

## Components

### Operations dashboard

- [Operations dashboard](https://github.com/excelyynxl-a11y/fn-key/blob/main/client/src/pages/LandingPage.jsx): `client/src/pages/LandingPage.jsx`
- [API client](https://github.com/excelyynxl-a11y/fn-key/blob/main/client/src/services/api.js): `client/src/services/api.js`

### API and workflow

- [Express API](https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/app.js): `server/src/app.js`
- [Run controller](https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/controllers/runController.js): `server/src/controllers/runController.js`
- [Review controller](https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/controllers/reviewController.js): `server/src/controllers/reviewController.js`
- [Knowledge controller](https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/controllers/knowledgeController.js): `server/src/controllers/knowledgeController.js`
- [Run orchestration](https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/services/runService.js): `server/src/services/runService.js`
- [Inbox dataset](https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/repositories/datasetRepository.js): `server/src/repositories/datasetRepository.js`

### Verification pipeline

- [Email processing pipeline](https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/services/pipelineService.js): `server/src/services/pipelineService.js`
- [Adaptive classification](https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/services/adaptiveClassificationService.js): `server/src/services/adaptiveClassificationService.js`
- [Attachment parsing](https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/services/fileParserService.js): `server/src/services/fileParserService.js`
- [Document role detection](https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/services/documentTypeService.js): `server/src/services/documentTypeService.js`
- [Field extraction](https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/services/fieldExtractionService.js): `server/src/services/fieldExtractionService.js`
- [Field normalization](https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/services/normalizationService.js): `server/src/services/normalizationService.js`
- [Deterministic comparison](https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/services/comparisonService.js): `server/src/services/comparisonService.js`
- [Structured AI fallback](https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/services/documentAiService.js): `server/src/services/documentAiService.js`

### Review and learning

- [Review handling](https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/services/reviewService.js): `server/src/services/reviewService.js`
- [Knowledge and learning](https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/services/knowledgeService.js): `server/src/services/knowledgeService.js`

### Persistence and outputs

- [Run metrics](https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/services/metricsService.js): `server/src/services/metricsService.js`
- [Submission export](https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/services/submissionService.js): `server/src/services/submissionService.js`
- [Email results](https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/models/Email.js): `server/src/models/Email.js`
- [Processing runs](https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/models/ProcessingRun.js): `server/src/models/ProcessingRun.js`
- [Review cases](https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/models/ReviewCase.js): `server/src/models/ReviewCase.js`
- [Audit history](https://github.com/excelyynxl-a11y/fn-key/blob/main/server/src/models/AuditEvent.js): `server/src/models/AuditEvent.js`

### Other components

- **Operations user**
- **MongoDB**
- **OpenAI API**

## Connections

- Operations user → Operations dashboard: operates (evidence: `README.md`)
- Operations dashboard → API client: requests through (evidence: `client/src/pages/LandingPage.jsx`)
- API client → Express API: sends HTTP (evidence: `client/src/services/api.js`)
- Express API → Run controller: routes runs (evidence: `server/src/app.js`)
- Express API → Review controller: routes reviews (evidence: `server/src/app.js`)
- Express API → Knowledge controller: routes knowledge (evidence: `server/src/app.js`)
- Run controller → Run orchestration: starts runs (evidence: `server/src/controllers/runController.js`)
- Run orchestration → Inbox dataset: loads dataset (evidence: `server/src/services/runService.js`)
- Run orchestration → Email processing pipeline: processes emails (evidence: `server/src/services/runService.js`)
- Email processing pipeline → Adaptive classification: classifies (evidence: `server/src/services/pipelineService.js`)
- Email processing pipeline → Attachment parsing: parses attachments (evidence: `server/src/services/pipelineService.js`)
- Email processing pipeline → Document role detection: identifies roles (evidence: `server/src/services/pipelineService.js`)
- Email processing pipeline → Field extraction: extracts fields (evidence: `server/src/services/pipelineService.js`)
- Email processing pipeline → Field normalization: normalizes fields (evidence: `server/src/services/pipelineService.js`)
- Email processing pipeline → Deterministic comparison: compares documents (evidence: `server/src/services/pipelineService.js`)
- Email processing pipeline → Structured AI fallback: falls back to AI (evidence: `server/src/services/pipelineService.js`)
- Structured AI fallback → OpenAI API: requests structured output (evidence: `README.md`)
- Run orchestration → Email results: persists results (evidence: `README.md`)
- Run orchestration → Processing runs: tracks run state (evidence: `README.md`)
- Run orchestration → Review handling: routes exceptions (evidence: `README.md`)
- Review controller → Review handling: resolves and retries (evidence: `server/src/controllers/reviewController.js`)
- Review handling → Email processing pipeline: reprocesses corrections (evidence: `server/src/services/reviewService.js`)
- Review handling → Review cases: updates cases (evidence: `server/src/services/reviewService.js`)
- Review handling → Email results: updates reviewed email (evidence: `server/src/services/reviewService.js`)
- Review handling → Audit history: records decisions (evidence: `server/src/services/reviewService.js`)
- Review handling → Knowledge and learning: learns phrases (evidence: `server/src/services/reviewService.js`)
- Knowledge controller → Knowledge and learning: manages knowledge (evidence: `server/src/controllers/knowledgeController.js`)
- Run controller → Run metrics: gets metrics (evidence: `server/src/controllers/runController.js`)
- Run controller → Submission export: builds export (evidence: `server/src/controllers/runController.js`)
- Run controller → Email results: reads results (evidence: `server/src/controllers/runController.js`)
- Run metrics → Email results: reads email state (evidence: `server/src/services/metricsService.js`)
- Run metrics → Processing runs: reads run state (evidence: `server/src/services/metricsService.js`)
- Run metrics → Review cases: reads review state (evidence: `server/src/services/metricsService.js`)
- Email results → MongoDB: persists in (evidence: `README.md`)
- Processing runs → MongoDB: persists in (evidence: `README.md`)
- Review cases → MongoDB: persists in (evidence: `README.md`)
- Audit history → MongoDB: persists in (evidence: `README.md`)
