# jyz922/crack architecture

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

## Overview

CRACK analyzes joke text through scope filtering, lexical and contextual pun analysis, resolution checks, then age-specific comprehension and safety assessment. Its runner coordinates the layers; the web server exposes synchronous and streaming analysis. The README documents the full L0–L8 capability set. Edges follow shown imports and calls; some detailed ordering and data handoffs are not visible in the excerpts, so they are not inferred.

Main entry points: [`src/crack/runner.py`](https://github.com/jyz922/crack/blob/main/src/crack/runner.py) (Pipeline runner), [`src/crack/layers.py`](https://github.com/jyz922/crack/blob/main/src/crack/layers.py) (Layer registry), [`src/crack/providers.py`](https://github.com/jyz922/crack/blob/main/src/crack/providers.py) (LLM providers), [`src/crack/l7_comprehension.py`](https://github.com/jyz922/crack/blob/main/src/crack/l7_comprehension.py) (Age comprehension)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Analysis workflow"]
  node_layers["Layer registry<br/>[layers.py]"]
  node_scope["Scope filtering<br/>[l0_scope.py]"]
  node_surface["Surface analysis<br/>[l1_surface.py]"]
  node_senses["Sense retrieval<br/>[l2_senses.py]"]
  node_candidates["Candidate ranking<br/>[l3_candidates.py]"]
  node_anchoring["Sense anchoring<br/>[l4_anchoring.py]"]
  node_resolution["Pun resolution<br/>[l5_resolution.py]"]
  node_distinctness["Sense distinctness<br/>[l6_distinctness.py]"]
end

subgraph group_development["Developmental assessment"]
  node_comprehension["Age comprehension"]
  node_appropriateness["Age safety"]
end

subgraph group_runtime["Runtime and interfaces"]
  node_runner["Pipeline runner<br/>[runner.py]"]
  node_corpus["Corpus utilities<br/>[corpus.py]"]
  node_web["Web API and stream<br/>[serve.py]"]
end

subgraph group_shared["Shared foundations"]
  node_providers["LLM providers<br/>[providers.py]"]
  node_config["Pipeline settings<br/>[config.py]"]
  node_schema["Analysis records<br/>[schema.py]"]
  node_enums["Status vocabulary<br/>[enums.py]"]
  node_lexical[("WordNet and AoA")]
end

node_user(("Analyst"))

node_user -->|"submits text"| node_web
node_user -->|"submits analysis"| node_runner
node_web -->|"runs analysis"| node_runner
node_runner -->|"preprocesses input"| node_scope
node_runner -->|"dispatches layer"| node_surface
node_runner -->|"dispatches layer"| node_senses
node_runner -->|"dispatches layer"| node_candidates
node_runner -->|"dispatches layer"| node_anchoring
node_runner -->|"dispatches layer"| node_resolution
node_runner -->|"dispatches layer"| node_distinctness
node_runner -->|"dispatches layer"| node_comprehension
node_runner -->|"dispatches layer"| node_appropriateness
node_runner -->|"uses corpus"| node_corpus
node_layers -->|"retrieves senses"| node_senses
node_layers -->|"ranks candidates"| node_candidates
node_layers -->|"anchors senses"| node_anchoring
node_layers -->|"scores resolution"| node_resolution
node_layers -->|"checks distinction"| node_distinctness
node_layers -->|"assesses comprehension"| node_comprehension
node_layers -->|"assesses safety"| node_appropriateness
node_senses -->|"queries lexicon"| node_lexical
node_comprehension -->|"uses sense data"| node_senses
node_appropriateness -->|"uses age results"| node_comprehension
node_anchoring -->|"calls model"| node_providers
node_resolution -->|"calls model"| node_providers
node_distinctness -->|"calls model"| node_providers
node_comprehension -->|"calls model"| node_providers
node_appropriateness -->|"calls model"| node_providers
node_runner -->|"loads settings"| node_config
node_runner -->|"builds records"| node_schema
node_web -->|"configures settings"| node_config
node_web -->|"builds records"| node_schema
node_config -->|"selects backends"| node_providers
node_schema -->|"types statuses"| node_enums
node_scope -->|"assigns scope"| node_enums

click node_runner "https://github.com/jyz922/crack/blob/main/src/crack/runner.py"
click node_layers "https://github.com/jyz922/crack/blob/main/src/crack/layers.py"
click node_scope "https://github.com/jyz922/crack/blob/main/src/crack/l0_scope.py"
click node_surface "https://github.com/jyz922/crack/blob/main/src/crack/l1_surface.py"
click node_senses "https://github.com/jyz922/crack/blob/main/src/crack/l2_senses.py"
click node_candidates "https://github.com/jyz922/crack/blob/main/src/crack/l3_candidates.py"
click node_anchoring "https://github.com/jyz922/crack/blob/main/src/crack/l4_anchoring.py"
click node_resolution "https://github.com/jyz922/crack/blob/main/src/crack/l5_resolution.py"
click node_distinctness "https://github.com/jyz922/crack/blob/main/src/crack/l6_distinctness.py"
click node_comprehension "https://github.com/jyz922/crack/blob/main/src/crack/l7_comprehension.py"
click node_appropriateness "https://github.com/jyz922/crack/blob/main/src/crack/l8_appropriateness.py"
click node_corpus "https://github.com/jyz922/crack/blob/main/src/crack/corpus.py"
click node_web "https://github.com/jyz922/crack/blob/main/src/crack/serve.py"
click node_providers "https://github.com/jyz922/crack/blob/main/src/crack/providers.py"
click node_config "https://github.com/jyz922/crack/blob/main/src/crack/config.py"
click node_schema "https://github.com/jyz922/crack/blob/main/src/crack/schema.py"
click node_enums "https://github.com/jyz922/crack/blob/main/src/crack/enums.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_layers,node_scope,node_surface,node_senses,node_candidates,node_anchoring,node_resolution,node_distinctness toneBlue
class node_comprehension,node_appropriateness toneAmber
class node_runner,node_corpus,node_web toneMint
class node_providers,node_config,node_schema,node_enums,node_lexical toneRose
class node_user toneIndigo
```

## Components

### Analysis workflow

- [Layer registry](https://github.com/jyz922/crack/blob/main/src/crack/layers.py): `src/crack/layers.py`
- [Scope filtering](https://github.com/jyz922/crack/blob/main/src/crack/l0_scope.py): `src/crack/l0_scope.py`
- [Surface analysis](https://github.com/jyz922/crack/blob/main/src/crack/l1_surface.py): `src/crack/l1_surface.py`
- [Sense retrieval](https://github.com/jyz922/crack/blob/main/src/crack/l2_senses.py): `src/crack/l2_senses.py`
- [Candidate ranking](https://github.com/jyz922/crack/blob/main/src/crack/l3_candidates.py): `src/crack/l3_candidates.py`
- [Sense anchoring](https://github.com/jyz922/crack/blob/main/src/crack/l4_anchoring.py): `src/crack/l4_anchoring.py`
- [Pun resolution](https://github.com/jyz922/crack/blob/main/src/crack/l5_resolution.py): `src/crack/l5_resolution.py`
- [Sense distinctness](https://github.com/jyz922/crack/blob/main/src/crack/l6_distinctness.py): `src/crack/l6_distinctness.py`

### Developmental assessment

- [Age comprehension](https://github.com/jyz922/crack/blob/main/src/crack/l7_comprehension.py): `src/crack/l7_comprehension.py`
- [Age safety](https://github.com/jyz922/crack/blob/main/src/crack/l8_appropriateness.py): `src/crack/l8_appropriateness.py`

### Runtime and interfaces

- [Pipeline runner](https://github.com/jyz922/crack/blob/main/src/crack/runner.py): `src/crack/runner.py`
- [Corpus utilities](https://github.com/jyz922/crack/blob/main/src/crack/corpus.py): `src/crack/corpus.py`
- [Web API and stream](https://github.com/jyz922/crack/blob/main/src/crack/serve.py): `src/crack/serve.py`

### Shared foundations

- [LLM providers](https://github.com/jyz922/crack/blob/main/src/crack/providers.py): `src/crack/providers.py`
- [Pipeline settings](https://github.com/jyz922/crack/blob/main/src/crack/config.py): `src/crack/config.py`
- [Analysis records](https://github.com/jyz922/crack/blob/main/src/crack/schema.py): `src/crack/schema.py`
- [Status vocabulary](https://github.com/jyz922/crack/blob/main/src/crack/enums.py): `src/crack/enums.py`
- **WordNet and AoA**

### Other components

- **Analyst**

## Connections

- Analyst → Web API and stream: submits text (evidence: `src/crack/serve.py`)
- Analyst → Pipeline runner: submits analysis (evidence: `src/crack/runner.py`)
- Web API and stream → Pipeline runner: runs analysis (evidence: `src/crack/serve.py`)
- Pipeline runner → Scope filtering: preprocesses input (evidence: `src/crack/runner.py`)
- Pipeline runner → Surface analysis: dispatches layer
- Pipeline runner → Sense retrieval: dispatches layer
- Pipeline runner → Candidate ranking: dispatches layer
- Pipeline runner → Sense anchoring: dispatches layer
- Pipeline runner → Pun resolution: dispatches layer
- Pipeline runner → Sense distinctness: dispatches layer
- Pipeline runner → Age comprehension: dispatches layer
- Pipeline runner → Age safety: dispatches layer
- Pipeline runner → Corpus utilities: uses corpus (evidence: `src/crack/runner.py`)
- Layer registry → Sense retrieval: retrieves senses (evidence: `src/crack/layers.py`)
- Layer registry → Candidate ranking: ranks candidates (evidence: `src/crack/layers.py`)
- Layer registry → Sense anchoring: anchors senses (evidence: `src/crack/layers.py`)
- Layer registry → Pun resolution: scores resolution (evidence: `src/crack/layers.py`)
- Layer registry → Sense distinctness: checks distinction (evidence: `src/crack/layers.py`)
- Layer registry → Age comprehension: assesses comprehension (evidence: `src/crack/layers.py`)
- Layer registry → Age safety: assesses safety (evidence: `src/crack/layers.py`)
- Sense retrieval → WordNet and AoA: queries lexicon (evidence: `src/crack/l2_senses.py`)
- Age comprehension → Sense retrieval: uses sense data (evidence: `src/crack/l7_comprehension.py`)
- Age safety → Age comprehension: uses age results (evidence: `src/crack/l8_appropriateness.py`)
- Sense anchoring → LLM providers: calls model (evidence: `src/crack/l4_anchoring.py`)
- Pun resolution → LLM providers: calls model (evidence: `src/crack/l5_resolution.py`)
- Sense distinctness → LLM providers: calls model (evidence: `src/crack/l6_distinctness.py`)
- Age comprehension → LLM providers: calls model (evidence: `src/crack/l7_comprehension.py`)
- Age safety → LLM providers: calls model (evidence: `src/crack/l8_appropriateness.py`)
- Pipeline runner → Pipeline settings: loads settings (evidence: `src/crack/runner.py`)
- Pipeline runner → Analysis records: builds records (evidence: `src/crack/runner.py`)
- Web API and stream → Pipeline settings: configures settings (evidence: `src/crack/serve.py`)
- Web API and stream → Analysis records: builds records (evidence: `src/crack/serve.py`)
- Pipeline settings → LLM providers: selects backends (evidence: `src/crack/config.py`)
- Analysis records → Status vocabulary: types statuses (evidence: `src/crack/schema.py`)
- Scope filtering → Status vocabulary: assigns scope (evidence: `src/crack/l0_scope.py`)