# joannapreethi28/icc-26 architecture

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

- Interactive diagram: https://gitdiagram.com/joannapreethi28/icc-26
- Repository: https://github.com/joannapreethi28/icc-26

## Overview

Make AI Know Her is a multilingual cricket-answer layer that intervenes on gender-neutral questions: it classifies the query, applies a policy, retrieves verified or computed facts, then renders a sourced answer. Users reach the shared resolver through REST/MCP or the demo UI. The repository also includes model training and classifier evaluation. Some links are documented only at the pipeline level; unsampled implementation details are not inferred.

Main entry points: [`src/mak/pipeline.py`](https://github.com/joannapreethi28/icc-26/blob/main/src/mak/pipeline.py) (Resolution pipeline), [`src/mak/nlu/understand.py`](https://github.com/joannapreethi28/icc-26/blob/main/src/mak/nlu/understand.py) (Query parser), [`src/mak/fetch/facts.py`](https://github.com/joannapreethi28/icc-26/blob/main/src/mak/fetch/facts.py) (Fact retrieval), [`src/mak/api/service.py`](https://github.com/joannapreethi28/icc-26/blob/main/src/mak/api/service.py) (Validated service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_serving["Serving"]
  node_api["REST and MCP<br/>[app.py]"]
  node_demo["Demo UI<br/>[demo.py]"]
  node_service["Validated service<br/>[service.py]"]
  node_pipeline["Resolution pipeline<br/>[pipeline.py]"]
end

subgraph group_understanding["Query understanding"]
  node_understand["Query parser<br/>[understand.py]"]
  node_rules["Rules classifier<br/>[rules.py]"]
  node_laya["Laya classifier<br/>[laya_head.py]"]
  node_entities["Entity matching<br/>[entities.py]"]
  node_people["People registry<br/>[people.py]"]
  node_wikidata["Wikidata registry<br/>[wikidata.py]"]
end

subgraph group_answers["Facts and answers"]
  node_policy["Decision policy<br/>[decide.py]"]
  node_catalogue["Intent catalogue<br/>[catalogue.py]"]
  node_facts["Fact retrieval<br/>[facts.py]"]
  node_golden["Verified records<br/>[golden.py]"]
  node_compute["Computed records<br/>[compute.py]"]
  node_leader["Leader lookup<br/>[leader.py]"]
  node_render["Answer rendering<br/>[render.py]"]
end

subgraph group_model_quality["Model and evaluation"]
  node_training["Laya fine-tuning<br/>[train_laya.py]"]
  node_evaluation["Classifier evaluation<br/>[classifier_eval.py]"]
end

node_user(("Questioner"))

node_user -->|"submits query"| node_api
node_user -->|"uses demo"| node_demo
node_api -->|"routes requests"| node_service
node_demo -->|"calls resolver"| node_service
node_service -->|"resolves query"| node_pipeline
node_pipeline -->|"parses query"| node_understand
node_pipeline -->|"looks up intent"| node_catalogue
node_pipeline -->|"decides intervention"| node_policy
node_pipeline -->|"fetches facts"| node_facts
node_pipeline -->|"renders answer"| node_render
node_understand -->|"uses rules"| node_rules
node_understand -->|"uses model"| node_laya
node_understand -->|"matches entities"| node_entities
node_entities -->|"looks up names"| node_people
node_facts -->|"loads verified facts"| node_golden
node_facts -->|"uses computed records"| node_compute
node_facts -->|"uses player registry"| node_people
node_golden -->|"loads leaders"| node_leader
node_render -->|"uses leader data"| node_leader
node_wikidata -->|"updates registry"| node_people
node_training -->|"trains classifier"| node_laya
node_evaluation -->|"evaluates classifier"| node_rules
node_evaluation -->|"evaluates parser"| node_understand

click node_api "https://github.com/joannapreethi28/icc-26/blob/main/src/mak/api/app.py"
click node_demo "https://github.com/joannapreethi28/icc-26/blob/main/src/mak/ui/demo.py"
click node_service "https://github.com/joannapreethi28/icc-26/blob/main/src/mak/api/service.py"
click node_pipeline "https://github.com/joannapreethi28/icc-26/blob/main/src/mak/pipeline.py"
click node_understand "https://github.com/joannapreethi28/icc-26/blob/main/src/mak/nlu/understand.py"
click node_rules "https://github.com/joannapreethi28/icc-26/blob/main/src/mak/nlu/rules.py"
click node_laya "https://github.com/joannapreethi28/icc-26/blob/main/src/mak/nlu/laya_head.py"
click node_entities "https://github.com/joannapreethi28/icc-26/blob/main/src/mak/nlu/entities.py"
click node_people "https://github.com/joannapreethi28/icc-26/blob/main/src/mak/registry/people.py"
click node_policy "https://github.com/joannapreethi28/icc-26/blob/main/src/mak/policy/decide.py"
click node_catalogue "https://github.com/joannapreethi28/icc-26/blob/main/src/mak/fetch/catalogue.py"
click node_facts "https://github.com/joannapreethi28/icc-26/blob/main/src/mak/fetch/facts.py"
click node_golden "https://github.com/joannapreethi28/icc-26/blob/main/src/mak/records/golden.py"
click node_compute "https://github.com/joannapreethi28/icc-26/blob/main/src/mak/records/compute.py"
click node_leader "https://github.com/joannapreethi28/icc-26/blob/main/src/mak/records/leader.py"
click node_render "https://github.com/joannapreethi28/icc-26/blob/main/src/mak/compose/render.py"
click node_wikidata "https://github.com/joannapreethi28/icc-26/blob/main/src/mak/registry/wikidata.py"
click node_training "https://github.com/joannapreethi28/icc-26/blob/main/training/finetune/train_laya.py"
click node_evaluation "https://github.com/joannapreethi28/icc-26/blob/main/src/mak/eval/classifier_eval.py"

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_api,node_demo,node_service,node_pipeline toneBlue
class node_understand,node_rules,node_laya,node_entities,node_people,node_wikidata toneAmber
class node_policy,node_catalogue,node_facts,node_golden,node_compute,node_leader,node_render toneMint
class node_training,node_evaluation toneRose
class node_user toneIndigo
```

## Components

### Serving

- [REST and MCP](https://github.com/joannapreethi28/icc-26/blob/main/src/mak/api/app.py): `src/mak/api/app.py`
- [Demo UI](https://github.com/joannapreethi28/icc-26/blob/main/src/mak/ui/demo.py): `src/mak/ui/demo.py`
- [Validated service](https://github.com/joannapreethi28/icc-26/blob/main/src/mak/api/service.py): `src/mak/api/service.py`
- [Resolution pipeline](https://github.com/joannapreethi28/icc-26/blob/main/src/mak/pipeline.py): `src/mak/pipeline.py`

### Query understanding

- [Query parser](https://github.com/joannapreethi28/icc-26/blob/main/src/mak/nlu/understand.py): `src/mak/nlu/understand.py`
- [Rules classifier](https://github.com/joannapreethi28/icc-26/blob/main/src/mak/nlu/rules.py): `src/mak/nlu/rules.py`
- [Laya classifier](https://github.com/joannapreethi28/icc-26/blob/main/src/mak/nlu/laya_head.py): `src/mak/nlu/laya_head.py`
- [Entity matching](https://github.com/joannapreethi28/icc-26/blob/main/src/mak/nlu/entities.py): `src/mak/nlu/entities.py`
- [People registry](https://github.com/joannapreethi28/icc-26/blob/main/src/mak/registry/people.py): `src/mak/registry/people.py`
- [Wikidata registry](https://github.com/joannapreethi28/icc-26/blob/main/src/mak/registry/wikidata.py): `src/mak/registry/wikidata.py`

### Facts and answers

- [Decision policy](https://github.com/joannapreethi28/icc-26/blob/main/src/mak/policy/decide.py): `src/mak/policy/decide.py`
- [Intent catalogue](https://github.com/joannapreethi28/icc-26/blob/main/src/mak/fetch/catalogue.py): `src/mak/fetch/catalogue.py`
- [Fact retrieval](https://github.com/joannapreethi28/icc-26/blob/main/src/mak/fetch/facts.py): `src/mak/fetch/facts.py`
- [Verified records](https://github.com/joannapreethi28/icc-26/blob/main/src/mak/records/golden.py): `src/mak/records/golden.py`
- [Computed records](https://github.com/joannapreethi28/icc-26/blob/main/src/mak/records/compute.py): `src/mak/records/compute.py`
- [Leader lookup](https://github.com/joannapreethi28/icc-26/blob/main/src/mak/records/leader.py): `src/mak/records/leader.py`
- [Answer rendering](https://github.com/joannapreethi28/icc-26/blob/main/src/mak/compose/render.py): `src/mak/compose/render.py`

### Model and evaluation

- [Laya fine-tuning](https://github.com/joannapreethi28/icc-26/blob/main/training/finetune/train_laya.py): `training/finetune/train_laya.py`
- [Classifier evaluation](https://github.com/joannapreethi28/icc-26/blob/main/src/mak/eval/classifier_eval.py): `src/mak/eval/classifier_eval.py`

### Other components

- **Questioner**

## Connections

- Questioner → REST and MCP: submits query
- Questioner → Demo UI: uses demo
- REST and MCP → Validated service: routes requests (evidence: `src/mak/api/app.py`)
- Demo UI → Validated service: calls resolver (evidence: `src/mak/ui/demo.py`)
- Validated service → Resolution pipeline: resolves query (evidence: `src/mak/api/service.py`)
- Resolution pipeline → Query parser: parses query (evidence: `src/mak/pipeline.py`)
- Resolution pipeline → Intent catalogue: looks up intent (evidence: `src/mak/pipeline.py`)
- Resolution pipeline → Decision policy: decides intervention (evidence: `src/mak/pipeline.py`)
- Resolution pipeline → Fact retrieval: fetches facts (evidence: `src/mak/pipeline.py`)
- Resolution pipeline → Answer rendering: renders answer (evidence: `src/mak/pipeline.py`)
- Query parser → Rules classifier: uses rules (evidence: `src/mak/nlu/understand.py`)
- Query parser → Laya classifier: uses model (evidence: `src/mak/nlu/understand.py`)
- Query parser → Entity matching: matches entities (evidence: `src/mak/pipeline.py`)
- Entity matching → People registry: looks up names (evidence: `src/mak/nlu/entities.py`)
- Fact retrieval → Verified records: loads verified facts (evidence: `src/mak/fetch/facts.py`)
- Fact retrieval → Computed records: uses computed records (evidence: `src/mak/fetch/facts.py`)
- Fact retrieval → People registry: uses player registry (evidence: `src/mak/fetch/facts.py`)
- Verified records → Leader lookup: loads leaders (evidence: `src/mak/records/golden.py`)
- Answer rendering → Leader lookup: uses leader data (evidence: `src/mak/compose/render.py`)
- Wikidata registry → People registry: updates registry (evidence: `src/mak/registry/wikidata.py`)
- Laya fine-tuning → Laya classifier: trains classifier (evidence: `training/finetune/train_laya.py`)
- Classifier evaluation → Rules classifier: evaluates classifier (evidence: `src/mak/eval/classifier_eval.py`)
- Classifier evaluation → Query parser: evaluates parser (evidence: `src/mak/eval/classifier_eval.py`)
