# terboubomar/tadqeeq architecture

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

## Overview

Tadqeeq audits delivery-platform settlements and invoices. Users submit platform files; strict parsing feeds deterministic HungerStation, Keeta, and Jahez accounting engines, whose results drive exceptions and evidence for human review. AI is a separate explanation and insight layer: it receives server-built audited facts, not raw financial files, and cannot alter accounting results. The README documents these domain relationships; several route and persistence implementations were not sampled, so uncertain runtime links are omitted.

Main entry points: [`src/lib/analysis/types.ts`](https://github.com/terboubomar/tadqeeq/blob/main/src/lib/analysis/types.ts) (Audit results), [`src/lib/exceptions.ts`](https://github.com/terboubomar/tadqeeq/blob/main/src/lib/exceptions.ts) (Exception logic), [`src/lib/compensation-evidence.ts`](https://github.com/terboubomar/tadqeeq/blob/main/src/lib/compensation-evidence.ts) (Evidence trail), [`src/lib/ops.server.ts`](https://github.com/terboubomar/tadqeeq/blob/main/src/lib/ops.server.ts) (Operations admin)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_audit["Settlement audit"]
  node_import["File import<br/>[import.tsx]"]
  node_parse["Strict parser<br/>[parse.ts]"]
  node_platforms["Platform engines"]
  node_auditresult["Audit results<br/>[types.ts]"]
end

subgraph group_review["Exceptions and claims"]
  node_exceptions["Exception logic<br/>[exceptions.ts]"]
  node_evidence["Evidence trail"]
  node_compensation["Compensation cases"]
  node_contracts["Contract compliance"]
  node_telegram["Telegram intake"]
end

subgraph group_insight["AI and intelligence"]
  node_ai["Exception explanations"]
  node_periodsummary["Period summaries"]
  node_periodintel["Period intelligence"]
  node_ask["Ask Tadqeeq"]
  node_factregistry["Fact registry<br/>[analyst-context.ts]"]
end

subgraph group_workspace["Workspace operations"]
  node_workspace["Workspace access"]
  node_onboarding["Client onboarding<br/>[onboarding.ts]"]
  node_ops["Operations admin<br/>[ops.server.ts]"]
  node_opsui["Ops client tools<br/>[OpsClientForms.tsx]"]
  node_supabase[("Supabase services<br/>[client.server.ts]")]
end

node_user(("Finance user"))
node_reviewer(("Human reviewer"))

node_user -->|"uploads files"| node_import
node_import -->|"parses files"| node_parse
node_parse -->|"feeds engines"| node_platforms
node_platforms -->|"calculates results"| node_auditresult
node_auditresult -->|"identifies exceptions"| node_exceptions
node_exceptions -->|"builds evidence"| node_evidence
node_evidence -->|"supports review"| node_reviewer
node_exceptions -->|"explains audited facts"| node_ai
node_auditresult -->|"summarizes metrics"| node_periodsummary
node_auditresult -->|"compares periods"| node_periodintel
node_factregistry -->|"grounds answers"| node_ask
node_auditresult -->|"provides audited facts"| node_factregistry
node_evidence -.->|"supports claims"| node_compensation
node_user -.->|"requests access"| node_workspace
node_workspace -->|"checks access"| node_supabase
node_opsui -->|"submits client updates"| node_ops
node_ops -->|"reads and writes"| node_supabase
node_ops -->|"loads suspension data"| node_onboarding
node_telegram -->|"stores intake data"| node_supabase

click node_import "https://github.com/terboubomar/tadqeeq/blob/main/src/routes/_authenticated/import.tsx"
click node_parse "https://github.com/terboubomar/tadqeeq/blob/main/src/lib/analysis/parse.ts"
click node_platforms "https://github.com/terboubomar/tadqeeq/tree/main/src/lib/analysis"
click node_auditresult "https://github.com/terboubomar/tadqeeq/blob/main/src/lib/analysis/types.ts"
click node_exceptions "https://github.com/terboubomar/tadqeeq/blob/main/src/lib/exceptions.ts"
click node_evidence "https://github.com/terboubomar/tadqeeq/blob/main/src/lib/compensation-evidence.ts"
click node_compensation "https://github.com/terboubomar/tadqeeq/tree/main/src/routes/compensation"
click node_contracts "https://github.com/terboubomar/tadqeeq/blob/main/src/lib/contract-compliance.ts"
click node_ai "https://github.com/terboubomar/tadqeeq/blob/main/src/lib/ai/exception-ai.server.ts"
click node_periodsummary "https://github.com/terboubomar/tadqeeq/blob/main/src/lib/ai/period-summary-ai.server.ts"
click node_periodintel "https://github.com/terboubomar/tadqeeq/blob/main/src/lib/period-intelligence.ts"
click node_ask "https://github.com/terboubomar/tadqeeq/blob/main/src/lib/ai/analyst-ai.server.ts"
click node_factregistry "https://github.com/terboubomar/tadqeeq/blob/main/src/lib/ai/analyst-context.ts"
click node_workspace "https://github.com/terboubomar/tadqeeq/blob/main/src/lib/workspace-access.ts"
click node_onboarding "https://github.com/terboubomar/tadqeeq/blob/main/src/lib/onboarding.ts"
click node_ops "https://github.com/terboubomar/tadqeeq/blob/main/src/lib/ops.server.ts"
click node_opsui "https://github.com/terboubomar/tadqeeq/blob/main/src/components/OpsClientForms.tsx"
click node_supabase "https://github.com/terboubomar/tadqeeq/blob/main/src/integrations/supabase/client.server.ts"
click node_telegram "https://github.com/terboubomar/tadqeeq/blob/main/src/lib/telegram-webhook.server.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_import,node_parse,node_platforms,node_auditresult,node_user,node_reviewer toneBlue
class node_exceptions,node_evidence,node_compensation,node_contracts,node_telegram toneAmber
class node_ai,node_periodsummary,node_periodintel,node_ask,node_factregistry toneMint
class node_workspace,node_onboarding,node_ops,node_opsui,node_supabase toneRose
```

## Components

### Settlement audit

- [File import](https://github.com/terboubomar/tadqeeq/blob/main/src/routes/_authenticated/import.tsx): `src/routes/_authenticated/import.tsx`
- [Strict parser](https://github.com/terboubomar/tadqeeq/blob/main/src/lib/analysis/parse.ts): `src/lib/analysis/parse.ts`
- [Platform engines](https://github.com/terboubomar/tadqeeq/tree/main/src/lib/analysis): `src/lib/analysis`
- [Audit results](https://github.com/terboubomar/tadqeeq/blob/main/src/lib/analysis/types.ts): `src/lib/analysis/types.ts`

### Exceptions and claims

- [Exception logic](https://github.com/terboubomar/tadqeeq/blob/main/src/lib/exceptions.ts): `src/lib/exceptions.ts`
- [Evidence trail](https://github.com/terboubomar/tadqeeq/blob/main/src/lib/compensation-evidence.ts): `src/lib/compensation-evidence.ts`
- [Compensation cases](https://github.com/terboubomar/tadqeeq/tree/main/src/routes/compensation): `src/routes/compensation`
- [Contract compliance](https://github.com/terboubomar/tadqeeq/blob/main/src/lib/contract-compliance.ts): `src/lib/contract-compliance.ts`
- [Telegram intake](https://github.com/terboubomar/tadqeeq/blob/main/src/lib/telegram-webhook.server.ts): `src/lib/telegram-webhook.server.ts`

### AI and intelligence

- [Exception explanations](https://github.com/terboubomar/tadqeeq/blob/main/src/lib/ai/exception-ai.server.ts): `src/lib/ai/exception-ai.server.ts`
- [Period summaries](https://github.com/terboubomar/tadqeeq/blob/main/src/lib/ai/period-summary-ai.server.ts): `src/lib/ai/period-summary-ai.server.ts`
- [Period intelligence](https://github.com/terboubomar/tadqeeq/blob/main/src/lib/period-intelligence.ts): `src/lib/period-intelligence.ts`
- [Ask Tadqeeq](https://github.com/terboubomar/tadqeeq/blob/main/src/lib/ai/analyst-ai.server.ts): `src/lib/ai/analyst-ai.server.ts`
- [Fact registry](https://github.com/terboubomar/tadqeeq/blob/main/src/lib/ai/analyst-context.ts): `src/lib/ai/analyst-context.ts`

### Workspace operations

- [Workspace access](https://github.com/terboubomar/tadqeeq/blob/main/src/lib/workspace-access.ts): `src/lib/workspace-access.ts`
- [Client onboarding](https://github.com/terboubomar/tadqeeq/blob/main/src/lib/onboarding.ts): `src/lib/onboarding.ts`
- [Operations admin](https://github.com/terboubomar/tadqeeq/blob/main/src/lib/ops.server.ts): `src/lib/ops.server.ts`
- [Ops client tools](https://github.com/terboubomar/tadqeeq/blob/main/src/components/OpsClientForms.tsx): `src/components/OpsClientForms.tsx`
- [Supabase services](https://github.com/terboubomar/tadqeeq/blob/main/src/integrations/supabase/client.server.ts): `src/integrations/supabase/client.server.ts`

### Other components

- **Finance user**
- **Human reviewer**

## Connections

- Finance user → File import: uploads files
- File import → Strict parser: parses files
- Strict parser → Platform engines: feeds engines
- Platform engines → Audit results: calculates results
- Audit results → Exception logic: identifies exceptions
- Exception logic → Evidence trail: builds evidence
- Evidence trail → Human reviewer: supports review
- Exception logic → Exception explanations: explains audited facts
- Audit results → Period summaries: summarizes metrics
- Audit results → Period intelligence: compares periods
- Fact registry → Ask Tadqeeq: grounds answers
- Audit results → Fact registry: provides audited facts (evidence: `src/lib/ai/analyst-context.ts`)
- Evidence trail → Compensation cases: supports claims
- Finance user → Workspace access: requests access
- Workspace access → Supabase services: checks access
- Ops client tools → Operations admin: submits client updates (evidence: `src/components/OpsClientForms.tsx`)
- Operations admin → Supabase services: reads and writes (evidence: `src/lib/ops.server.ts`)
- Operations admin → Client onboarding: loads suspension data (evidence: `src/lib/ops.server.ts`)
- Telegram intake → Supabase services: stores intake data (evidence: `src/lib/telegram-webhook.server.ts`)
