# onielrosario/frameit architecture

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

- Interactive diagram: https://gitdiagram.com/onielrosario/frameit
- Repository: https://github.com/onielrosario/frameit

## Overview

Frame is a Chrome extension backed by a FastAPI service that analyzes selected text with Gemini and returns a validated framing read with evidence. The main workflow runs from page selection through the extension worker to the API, where text is normalized, model output is validated, quoted evidence is recovered from the selection, and surviving signals are scored into the response. The repository also includes a reviewer-agreement evaluation harness. The README documents the end-to-end client/server workflow; some extension message wiring and evaluation internals are not shown in excerpts, so those links are omitted or marked unverified.

Main entry points: [`services/api/app/api/routes.py`](https://github.com/onielrosario/frameit/blob/main/services/api/app/api/routes.py) (Analyze endpoint), [`services/api/app/analysis/pipeline.py`](https://github.com/onielrosario/frameit/blob/main/services/api/app/analysis/pipeline.py) (Analysis pipeline), [`apps/extension/src/content/Overlay.tsx`](https://github.com/onielrosario/frameit/blob/main/apps/extension/src/content/Overlay.tsx) (Page overlay), [`evaluation/runners/frame_eval/cli.py`](https://github.com/onielrosario/frameit/blob/main/evaluation/runners/frame_eval/cli.py) (Evaluation runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extension["Chrome extension"]
  node_overlay["Page overlay<br/>[Overlay.tsx]"]
  node_content_entry["Content entry<br/>[index.ts]"]
  node_worker["Background worker<br/>[index.ts]"]
  node_api_client["API client<br/>[client.ts]"]
  node_contract["Response contract<br/>[contract.ts]"]
  node_popup["Settings popup<br/>[App.tsx]"]
  node_settings["Extension settings<br/>[settings.ts]"]
end

subgraph group_analysis["API analysis"]
  node_api_routes["Analyze endpoint<br/>[routes.py]"]
  node_normalizer["Text normalizer<br/>[normalize.py]"]
  node_gemini["Gemini analyzer<br/>[gemini.py]"]
  node_model_output["Model output schema<br/>[model_output.py]"]
  node_pipeline["Analysis pipeline<br/>[pipeline.py]"]
  node_recovery["Evidence recovery<br/>[recover.py]"]
  node_scoring["Provisional scoring<br/>[provisional.py]"]
  node_taxonomy["Analysis taxonomy<br/>[taxonomy.py]"]
  node_response_models["Response models<br/>[analysis.py]"]
end

subgraph group_evaluation["Evaluation harness"]
  node_eval_cli["Evaluation runner<br/>[cli.py]"]
  node_eval_records["Evaluation records<br/>[records.py]"]
  node_eval_metrics["Agreement metrics<br/>[metrics.py]"]
  node_eval_report["Evaluation report<br/>[report.py]"]
end

node_user(("Page reader"))

node_user -->|"selects text"| node_overlay
node_overlay -->|"renders through"| node_content_entry
node_content_entry -->|"mounts"| node_overlay
node_overlay -.->|"sends request"| node_worker
node_worker -->|"calls"| node_api_client
node_worker -->|"reads"| node_settings
node_api_client -->|"posts selection"| node_api_routes
node_api_client -->|"validates response"| node_contract
node_popup -->|"reads and saves"| node_settings
node_api_routes -->|"normalizes text"| node_normalizer
node_api_routes -->|"invokes analyzer"| node_gemini
node_api_routes -->|"builds response"| node_pipeline
node_gemini -->|"parses output"| node_model_output
node_model_output -->|"uses enums"| node_taxonomy
node_pipeline -->|"recovers excerpts"| node_recovery
node_pipeline -->|"scores survivors"| node_scoring
node_pipeline -->|"constructs response"| node_response_models
node_response_models -->|"uses enums"| node_taxonomy
node_eval_cli -->|"loads records"| node_eval_records
node_eval_cli -->|"computes metrics"| node_eval_metrics
node_eval_cli -->|"creates report"| node_eval_report
node_eval_report -->|"summarizes metrics"| node_eval_metrics

click node_overlay "https://github.com/onielrosario/frameit/blob/main/apps/extension/src/content/Overlay.tsx"
click node_content_entry "https://github.com/onielrosario/frameit/blob/main/apps/extension/src/content/index.ts"
click node_worker "https://github.com/onielrosario/frameit/blob/main/apps/extension/src/background/index.ts"
click node_api_client "https://github.com/onielrosario/frameit/blob/main/apps/extension/src/api/client.ts"
click node_contract "https://github.com/onielrosario/frameit/blob/main/apps/extension/src/api/contract.ts"
click node_popup "https://github.com/onielrosario/frameit/blob/main/apps/extension/src/popup/App.tsx"
click node_settings "https://github.com/onielrosario/frameit/blob/main/apps/extension/src/settings.ts"
click node_api_routes "https://github.com/onielrosario/frameit/blob/main/services/api/app/api/routes.py"
click node_normalizer "https://github.com/onielrosario/frameit/blob/main/services/api/app/evidence/normalize.py"
click node_gemini "https://github.com/onielrosario/frameit/blob/main/services/api/app/analysis/gemini.py"
click node_model_output "https://github.com/onielrosario/frameit/blob/main/services/api/app/analysis/model_output.py"
click node_pipeline "https://github.com/onielrosario/frameit/blob/main/services/api/app/analysis/pipeline.py"
click node_recovery "https://github.com/onielrosario/frameit/blob/main/services/api/app/evidence/recover.py"
click node_scoring "https://github.com/onielrosario/frameit/blob/main/services/api/app/scoring/provisional.py"
click node_taxonomy "https://github.com/onielrosario/frameit/blob/main/services/api/app/models/taxonomy.py"
click node_response_models "https://github.com/onielrosario/frameit/blob/main/services/api/app/models/analysis.py"
click node_eval_cli "https://github.com/onielrosario/frameit/blob/main/evaluation/runners/frame_eval/cli.py"
click node_eval_records "https://github.com/onielrosario/frameit/blob/main/evaluation/runners/frame_eval/records.py"
click node_eval_metrics "https://github.com/onielrosario/frameit/blob/main/evaluation/runners/frame_eval/metrics.py"
click node_eval_report "https://github.com/onielrosario/frameit/blob/main/evaluation/runners/frame_eval/report.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_overlay,node_content_entry,node_worker,node_api_client,node_contract,node_popup,node_settings toneBlue
class node_api_routes,node_normalizer,node_gemini,node_model_output,node_pipeline,node_recovery,node_scoring,node_taxonomy,node_response_models toneAmber
class node_eval_cli,node_eval_records,node_eval_metrics,node_eval_report toneMint
class node_user toneIndigo
```

## Components

### Chrome extension

- [Page overlay](https://github.com/onielrosario/frameit/blob/main/apps/extension/src/content/Overlay.tsx): `apps/extension/src/content/Overlay.tsx`
- [Content entry](https://github.com/onielrosario/frameit/blob/main/apps/extension/src/content/index.ts): `apps/extension/src/content/index.ts`
- [Background worker](https://github.com/onielrosario/frameit/blob/main/apps/extension/src/background/index.ts): `apps/extension/src/background/index.ts`
- [API client](https://github.com/onielrosario/frameit/blob/main/apps/extension/src/api/client.ts): `apps/extension/src/api/client.ts`
- [Response contract](https://github.com/onielrosario/frameit/blob/main/apps/extension/src/api/contract.ts): `apps/extension/src/api/contract.ts`
- [Settings popup](https://github.com/onielrosario/frameit/blob/main/apps/extension/src/popup/App.tsx): `apps/extension/src/popup/App.tsx`
- [Extension settings](https://github.com/onielrosario/frameit/blob/main/apps/extension/src/settings.ts): `apps/extension/src/settings.ts`

### API analysis

- [Analyze endpoint](https://github.com/onielrosario/frameit/blob/main/services/api/app/api/routes.py): `services/api/app/api/routes.py`
- [Text normalizer](https://github.com/onielrosario/frameit/blob/main/services/api/app/evidence/normalize.py): `services/api/app/evidence/normalize.py`
- [Gemini analyzer](https://github.com/onielrosario/frameit/blob/main/services/api/app/analysis/gemini.py): `services/api/app/analysis/gemini.py`
- [Model output schema](https://github.com/onielrosario/frameit/blob/main/services/api/app/analysis/model_output.py): `services/api/app/analysis/model_output.py`
- [Analysis pipeline](https://github.com/onielrosario/frameit/blob/main/services/api/app/analysis/pipeline.py): `services/api/app/analysis/pipeline.py`
- [Evidence recovery](https://github.com/onielrosario/frameit/blob/main/services/api/app/evidence/recover.py): `services/api/app/evidence/recover.py`
- [Provisional scoring](https://github.com/onielrosario/frameit/blob/main/services/api/app/scoring/provisional.py): `services/api/app/scoring/provisional.py`
- [Analysis taxonomy](https://github.com/onielrosario/frameit/blob/main/services/api/app/models/taxonomy.py): `services/api/app/models/taxonomy.py`
- [Response models](https://github.com/onielrosario/frameit/blob/main/services/api/app/models/analysis.py): `services/api/app/models/analysis.py`

### Evaluation harness

- [Evaluation runner](https://github.com/onielrosario/frameit/blob/main/evaluation/runners/frame_eval/cli.py): `evaluation/runners/frame_eval/cli.py`
- [Evaluation records](https://github.com/onielrosario/frameit/blob/main/evaluation/runners/frame_eval/records.py): `evaluation/runners/frame_eval/records.py`
- [Agreement metrics](https://github.com/onielrosario/frameit/blob/main/evaluation/runners/frame_eval/metrics.py): `evaluation/runners/frame_eval/metrics.py`
- [Evaluation report](https://github.com/onielrosario/frameit/blob/main/evaluation/runners/frame_eval/report.py): `evaluation/runners/frame_eval/report.py`

### Other components

- **Page reader**

## Connections

- Page reader → Page overlay: selects text
- Page overlay → Content entry: renders through (evidence: `apps/extension/src/content/index.ts`)
- Content entry → Page overlay: mounts (evidence: `apps/extension/src/content/index.ts`)
- Page overlay → Background worker: sends request
- Background worker → API client: calls (evidence: `apps/extension/src/background/index.ts`)
- Background worker → Extension settings: reads (evidence: `apps/extension/src/background/index.ts`)
- API client → Analyze endpoint: posts selection
- API client → Response contract: validates response (evidence: `apps/extension/src/api/client.ts`)
- Settings popup → Extension settings: reads and saves (evidence: `apps/extension/src/popup/App.tsx`)
- Analyze endpoint → Text normalizer: normalizes text (evidence: `services/api/app/api/routes.py`)
- Analyze endpoint → Gemini analyzer: invokes analyzer (evidence: `services/api/app/api/routes.py`)
- Analyze endpoint → Analysis pipeline: builds response (evidence: `services/api/app/api/routes.py`)
- Gemini analyzer → Model output schema: parses output (evidence: `services/api/app/analysis/gemini.py`)
- Model output schema → Analysis taxonomy: uses enums (evidence: `services/api/app/analysis/model_output.py`)
- Analysis pipeline → Evidence recovery: recovers excerpts (evidence: `services/api/app/analysis/pipeline.py`)
- Analysis pipeline → Provisional scoring: scores survivors (evidence: `services/api/app/analysis/pipeline.py`)
- Analysis pipeline → Response models: constructs response (evidence: `services/api/app/analysis/pipeline.py`)
- Response models → Analysis taxonomy: uses enums (evidence: `services/api/app/models/analysis.py`)
- Evaluation runner → Evaluation records: loads records (evidence: `evaluation/runners/frame_eval/cli.py`)
- Evaluation runner → Agreement metrics: computes metrics (evidence: `evaluation/runners/frame_eval/cli.py`)
- Evaluation runner → Evaluation report: creates report (evidence: `evaluation/runners/frame_eval/cli.py`)
- Evaluation report → Agreement metrics: summarizes metrics (evidence: `evaluation/runners/frame_eval/report.py`)
