# pennywis404/hackathon architecture

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

- Interactive diagram: https://gitdiagram.com/pennywis404/hackathon
- Repository: https://github.com/pennywis404/hackathon

## Overview

This repository is a French-language assistant for reviewing company-meeting minutes (PV d’AG): it indexes internal reference documents, retrieves relevant passages, and produces cited recommendations. Its richer draft-review flow qualifies and scores a draft, finds comparable past acts, proposes edits, and returns a review result to the UI. The graph covers documented and indexed relationships; some modules are listed as core but were not excerpted, so their internal calls are not asserted.

Main entry points: [`scripts/review.py`](https://github.com/pennywis404/hackathon/blob/main/scripts/review.py) (Review orchestrator), [`ingest.py`](https://github.com/pennywis404/hackathon/blob/main/ingest.py) (Corpus ingestion), [`retrieval.py`](https://github.com/pennywis404/hackathon/blob/main/retrieval.py) (Passage retrieval), [`llm.py`](https://github.com/pennywis404/hackathon/blob/main/llm.py) (Mistral client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Review interface"]
  node_ui_page["Review page<br/>[page.tsx]"]
  node_review_api["Review API<br/>[route.ts]"]
  node_result_view["Review results<br/>[result-view.tsx]"]
  node_architecture_view["Architecture view"]
end

subgraph group_review["Draft review"]
  node_review_runner["Review orchestrator<br/>[review.py]"]
  node_qualify["Draft qualification<br/>[qualify.py]"]
  node_pipeline["Context preparation<br/>[pipeline.py]"]
  node_similar["Similar acts<br/>[similar.py]"]
  node_scoring["Quality scoring<br/>[scoring.py]"]
  node_redraft["Draft correction<br/>[redraft.py]"]
  node_respond["Review response<br/>[respond.py]"]
end

subgraph group_rag["RAG analysis"]
  node_analyze["Minutes analysis<br/>[analyze.py]"]
  node_retrieval["Passage retrieval<br/>[retrieval.py]"]
end

subgraph group_corpus["Corpus and services"]
  node_ingest["Corpus ingestion<br/>[ingest.py]"]
  node_sources["Source normalization<br/>[sources.py]"]
  node_chunking["Document chunking<br/>[chunking.py]"]
  node_ocr["Scanned PDF OCR<br/>[ocr.py]"]
  node_vector_db[("Vector index")]
  node_parent_store[("Parent passages<br/>[parents.py]")]
  node_llm["Mistral client<br/>[llm.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

node_user(("Reviewer"))

node_user -.->|"submits draft"| node_ui_page
node_ui_page -.->|"requests review"| node_review_api
node_review_api -.->|"runs review"| node_review_runner
node_review_runner -->|"qualifies"| node_qualify
node_review_runner -->|"prepares context"| node_pipeline
node_review_runner -->|"finds precedents"| node_similar
node_review_runner -->|"corrects draft"| node_redraft
node_review_runner -->|"generates response"| node_respond
node_review_runner -->|"scores draft"| node_scoring
node_review_api -.->|"returns review"| node_result_view
node_pipeline -->|"retrieves passages"| node_analyze
node_pipeline -->|"decomposes sections"| node_llm
node_analyze -->|"searches passages"| node_retrieval
node_analyze -->|"analyzes sections"| node_llm
node_ingest -->|"normalizes sources"| node_sources
node_ingest -->|"chunks PDFs"| node_chunking
node_chunking -.->|"extracts scanned text"| node_ocr
node_ingest -->|"embeds chunks"| node_llm
node_ingest -->|"writes chunks"| node_vector_db
node_ingest -->|"stores full passages"| node_parent_store
node_retrieval -->|"queries embeddings"| node_vector_db
node_retrieval -->|"loads parent text"| node_parent_store
node_llm -->|"reads settings"| node_config
node_ingest -->|"reads settings"| node_config
node_retrieval -->|"reads settings"| node_config

click node_ui_page "https://github.com/pennywis404/hackathon/blob/main/ui/app/page.tsx"
click node_review_api "https://github.com/pennywis404/hackathon/blob/main/ui/app/api/review/route.ts"
click node_result_view "https://github.com/pennywis404/hackathon/blob/main/ui/components/result-view.tsx"
click node_architecture_view "https://github.com/pennywis404/hackathon/blob/main/ui/app/architecture/architecture-view.tsx"
click node_review_runner "https://github.com/pennywis404/hackathon/blob/main/scripts/review.py"
click node_qualify "https://github.com/pennywis404/hackathon/blob/main/qualify.py"
click node_pipeline "https://github.com/pennywis404/hackathon/blob/main/pipeline.py"
click node_similar "https://github.com/pennywis404/hackathon/blob/main/similar.py"
click node_scoring "https://github.com/pennywis404/hackathon/blob/main/scoring.py"
click node_redraft "https://github.com/pennywis404/hackathon/blob/main/redraft.py"
click node_respond "https://github.com/pennywis404/hackathon/blob/main/respond.py"
click node_analyze "https://github.com/pennywis404/hackathon/blob/main/analyze.py"
click node_retrieval "https://github.com/pennywis404/hackathon/blob/main/retrieval.py"
click node_ingest "https://github.com/pennywis404/hackathon/blob/main/ingest.py"
click node_sources "https://github.com/pennywis404/hackathon/blob/main/sources.py"
click node_chunking "https://github.com/pennywis404/hackathon/blob/main/chunking.py"
click node_ocr "https://github.com/pennywis404/hackathon/blob/main/ocr.py"
click node_parent_store "https://github.com/pennywis404/hackathon/blob/main/parents.py"
click node_llm "https://github.com/pennywis404/hackathon/blob/main/llm.py"
click node_config "https://github.com/pennywis404/hackathon/blob/main/config.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_ui_page,node_review_api,node_result_view,node_architecture_view,node_user toneBlue
class node_review_runner,node_qualify,node_pipeline,node_similar,node_scoring,node_redraft,node_respond toneAmber
class node_analyze,node_retrieval toneMint
class node_ingest,node_sources,node_chunking,node_ocr,node_vector_db,node_parent_store,node_llm,node_config toneRose
```

## Components

### Review interface

- [Review page](https://github.com/pennywis404/hackathon/blob/main/ui/app/page.tsx): `ui/app/page.tsx`
- [Review API](https://github.com/pennywis404/hackathon/blob/main/ui/app/api/review/route.ts): `ui/app/api/review/route.ts`
- [Review results](https://github.com/pennywis404/hackathon/blob/main/ui/components/result-view.tsx): `ui/components/result-view.tsx`
- [Architecture view](https://github.com/pennywis404/hackathon/blob/main/ui/app/architecture/architecture-view.tsx): `ui/app/architecture/architecture-view.tsx`

### Draft review

- [Review orchestrator](https://github.com/pennywis404/hackathon/blob/main/scripts/review.py): `scripts/review.py`
- [Draft qualification](https://github.com/pennywis404/hackathon/blob/main/qualify.py): `qualify.py`
- [Context preparation](https://github.com/pennywis404/hackathon/blob/main/pipeline.py): `pipeline.py`
- [Similar acts](https://github.com/pennywis404/hackathon/blob/main/similar.py): `similar.py`
- [Quality scoring](https://github.com/pennywis404/hackathon/blob/main/scoring.py): `scoring.py`
- [Draft correction](https://github.com/pennywis404/hackathon/blob/main/redraft.py): `redraft.py`
- [Review response](https://github.com/pennywis404/hackathon/blob/main/respond.py): `respond.py`

### RAG analysis

- [Minutes analysis](https://github.com/pennywis404/hackathon/blob/main/analyze.py): `analyze.py`
- [Passage retrieval](https://github.com/pennywis404/hackathon/blob/main/retrieval.py): `retrieval.py`

### Corpus and services

- [Corpus ingestion](https://github.com/pennywis404/hackathon/blob/main/ingest.py): `ingest.py`
- [Source normalization](https://github.com/pennywis404/hackathon/blob/main/sources.py): `sources.py`
- [Document chunking](https://github.com/pennywis404/hackathon/blob/main/chunking.py): `chunking.py`
- [Scanned PDF OCR](https://github.com/pennywis404/hackathon/blob/main/ocr.py): `ocr.py`
- **Vector index**
- [Parent passages](https://github.com/pennywis404/hackathon/blob/main/parents.py): `parents.py`
- [Mistral client](https://github.com/pennywis404/hackathon/blob/main/llm.py): `llm.py`
- [Runtime configuration](https://github.com/pennywis404/hackathon/blob/main/config.py): `config.py`

### Other components

- **Reviewer**

## Connections

- Reviewer → Review page: submits draft
- Review page → Review API: requests review
- Review API → Review orchestrator: runs review
- Review orchestrator → Draft qualification: qualifies (evidence: `scripts/review.py`)
- Review orchestrator → Context preparation: prepares context (evidence: `scripts/review.py`)
- Review orchestrator → Similar acts: finds precedents (evidence: `scripts/review.py`)
- Review orchestrator → Draft correction: corrects draft (evidence: `scripts/review.py`)
- Review orchestrator → Review response: generates response (evidence: `scripts/review.py`)
- Review orchestrator → Quality scoring: scores draft (evidence: `scripts/review.py`)
- Review API → Review results: returns review
- Context preparation → Minutes analysis: retrieves passages (evidence: `pipeline.py`)
- Context preparation → Mistral client: decomposes sections (evidence: `pipeline.py`)
- Minutes analysis → Passage retrieval: searches passages (evidence: `analyze.py`)
- Minutes analysis → Mistral client: analyzes sections (evidence: `analyze.py`)
- Corpus ingestion → Source normalization: normalizes sources (evidence: `ingest.py`)
- Corpus ingestion → Document chunking: chunks PDFs (evidence: `ingest.py`)
- Document chunking → Scanned PDF OCR: extracts scanned text (evidence: `chunking.py`)
- Corpus ingestion → Mistral client: embeds chunks (evidence: `ingest.py`)
- Corpus ingestion → Vector index: writes chunks (evidence: `ingest.py`)
- Corpus ingestion → Parent passages: stores full passages (evidence: `ingest.py`)
- Passage retrieval → Vector index: queries embeddings (evidence: `retrieval.py`)
- Passage retrieval → Parent passages: loads parent text (evidence: `retrieval.py`)
- Mistral client → Runtime configuration: reads settings (evidence: `llm.py`)
- Corpus ingestion → Runtime configuration: reads settings (evidence: `ingest.py`)
- Passage retrieval → Runtime configuration: reads settings (evidence: `retrieval.py`)
