# tommy87166/tablade architecture

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

- Interactive diagram: https://gitdiagram.com/tommy87166/tablade
- Repository: https://github.com/tommy87166/tablade

## Overview

Tablade is a local desktop data-cleaning application: users edit a staged recipe, load and preview files, then process and export results. The Python session coordinates recipe state and execution; the engine applies registered transformations, while ingestion and export handle files and reports. The README also documents command-line use and an AI recipe-writing skill. Some subsystem links are omitted where the available excerpts do not show who invokes them; documented product capabilities are retained without asserting unsampled call paths.

Main entry points: [`src/tablade/api.py`](https://github.com/tommy87166/tablade/blob/main/src/tablade/api.py) (Desktop API), [`src/tablade/ingest/sources.py`](https://github.com/tommy87166/tablade/blob/main/src/tablade/ingest/sources.py) (Input readers), [`src/tablade/session.py`](https://github.com/tommy87166/tablade/blob/main/src/tablade/session.py) (Recipe session), [`src/tablade/engine/run.py`](https://github.com/tommy87166/tablade/blob/main/src/tablade/engine/run.py) (Recipe engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interfaces"]
  node_frontend["Recipe editor<br/>[App.tsx]"]
  node_bridge["JS bridge<br/>[bridge.ts]"]
  node_desktop["Desktop window<br/>[app.py]"]
  node_cli["Command line<br/>[cli.py]"]
  node_api["Desktop API<br/>[api.py]"]
end

subgraph group_recipe["Recipes and steps"]
  node_session["Recipe session<br/>[session.py]"]
  node_schema["Recipe schema<br/>[schema.py]"]
  node_validator["Recipe validator<br/>[validator.py]"]
  node_step_registry["Step registry<br/>[registry.py]"]
  node_step_base["Step interface<br/>[base.py]"]
  node_step_types["Cleaning steps"]
end

subgraph group_data["Data processing"]
  node_ingest["Input readers<br/>[sources.py]"]
  node_encoding["Encoding support<br/>[encoding.py]"]
  node_excel["Excel reader<br/>[excel.py]"]
  node_zip_reader["ZIP text reader<br/>[zip_lines.py]"]
  node_engine["Recipe engine<br/>[run.py]"]
end

subgraph group_outputs["Outputs and integrations"]
  node_outputs["Stage exports<br/>[outputs.py]"]
  node_manifest["Run manifest<br/>[manifest.py]"]
  node_skill["AI recipe skill<br/>[skill.py]"]
end

subgraph group_support["Runtime services"]
  node_usage["Usage status<br/>[usage.py]"]
  node_selftest["Self-test<br/>[selftest.py]"]
  node_update["Version check<br/>[update.py]"]
end

node_user(("User"))
node_cli_user(("CLI user"))
node_github["GitHub"]

node_user -->|"edits recipe"| node_frontend
node_frontend -->|"calls bridge"| node_bridge
node_bridge -->|"invokes API"| node_api
node_desktop -->|"exposes API"| node_api
node_cli_user -->|"runs recipe"| node_cli
node_api -->|"manages state"| node_session
node_session -->|"validates recipes"| node_schema
node_schema -->|"checks recipes"| node_validator
node_schema -->|"builds step models"| node_step_registry
node_step_registry -->|"uses interface"| node_step_base
node_step_types -->|"registers steps"| node_step_registry
node_session -->|"loads sources"| node_ingest
node_ingest -->|"decodes inputs"| node_encoding
node_ingest -->|"reads workbooks"| node_excel
node_ingest -->|"reads ZIP members"| node_zip_reader
node_session -->|"runs stages"| node_engine
node_engine -->|"scans inputs"| node_ingest
node_engine -->|"applies steps"| node_step_base
node_engine -->|"writes results"| node_outputs
node_outputs -->|"records run"| node_manifest
node_api -->|"provides skill"| node_skill
node_api -->|"runs checks"| node_selftest
node_api -->|"reports usage"| node_usage
node_api -->|"checks version"| node_update
node_update -->|"checks release"| node_github

click node_frontend "https://github.com/tommy87166/tablade/blob/main/frontend/src/App.tsx"
click node_bridge "https://github.com/tommy87166/tablade/blob/main/frontend/src/bridge.ts"
click node_desktop "https://github.com/tommy87166/tablade/blob/main/src/tablade/app.py"
click node_cli "https://github.com/tommy87166/tablade/blob/main/src/tablade/cli.py"
click node_api "https://github.com/tommy87166/tablade/blob/main/src/tablade/api.py"
click node_session "https://github.com/tommy87166/tablade/blob/main/src/tablade/session.py"
click node_schema "https://github.com/tommy87166/tablade/blob/main/src/tablade/recipe/schema.py"
click node_validator "https://github.com/tommy87166/tablade/blob/main/src/tablade/recipe/validator.py"
click node_step_registry "https://github.com/tommy87166/tablade/blob/main/src/tablade/steps/registry.py"
click node_step_base "https://github.com/tommy87166/tablade/blob/main/src/tablade/steps/base.py"
click node_step_types "https://github.com/tommy87166/tablade/tree/main/src/tablade/steps"
click node_ingest "https://github.com/tommy87166/tablade/blob/main/src/tablade/ingest/sources.py"
click node_encoding "https://github.com/tommy87166/tablade/blob/main/src/tablade/ingest/encoding.py"
click node_excel "https://github.com/tommy87166/tablade/blob/main/src/tablade/ingest/excel.py"
click node_zip_reader "https://github.com/tommy87166/tablade/blob/main/src/tablade/ingest/zip_lines.py"
click node_engine "https://github.com/tommy87166/tablade/blob/main/src/tablade/engine/run.py"
click node_outputs "https://github.com/tommy87166/tablade/blob/main/src/tablade/export/outputs.py"
click node_manifest "https://github.com/tommy87166/tablade/blob/main/src/tablade/export/manifest.py"
click node_skill "https://github.com/tommy87166/tablade/blob/main/src/tablade/skill.py"
click node_usage "https://github.com/tommy87166/tablade/blob/main/src/tablade/usage.py"
click node_selftest "https://github.com/tommy87166/tablade/blob/main/src/tablade/selftest.py"
click node_update "https://github.com/tommy87166/tablade/blob/main/src/tablade/update.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_frontend,node_bridge,node_desktop,node_cli,node_api,node_user,node_cli_user toneBlue
class node_session,node_schema,node_validator,node_step_registry,node_step_base,node_step_types toneAmber
class node_ingest,node_encoding,node_excel,node_zip_reader,node_engine toneMint
class node_outputs,node_manifest,node_skill toneRose
class node_usage,node_selftest,node_update,node_github toneIndigo
```

## Components

### User interfaces

- [Recipe editor](https://github.com/tommy87166/tablade/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [JS bridge](https://github.com/tommy87166/tablade/blob/main/frontend/src/bridge.ts): `frontend/src/bridge.ts`
- [Desktop window](https://github.com/tommy87166/tablade/blob/main/src/tablade/app.py): `src/tablade/app.py`
- [Command line](https://github.com/tommy87166/tablade/blob/main/src/tablade/cli.py): `src/tablade/cli.py`
- [Desktop API](https://github.com/tommy87166/tablade/blob/main/src/tablade/api.py): `src/tablade/api.py`

### Recipes and steps

- [Recipe session](https://github.com/tommy87166/tablade/blob/main/src/tablade/session.py): `src/tablade/session.py`
- [Recipe schema](https://github.com/tommy87166/tablade/blob/main/src/tablade/recipe/schema.py): `src/tablade/recipe/schema.py`
- [Recipe validator](https://github.com/tommy87166/tablade/blob/main/src/tablade/recipe/validator.py): `src/tablade/recipe/validator.py`
- [Step registry](https://github.com/tommy87166/tablade/blob/main/src/tablade/steps/registry.py): `src/tablade/steps/registry.py`
- [Step interface](https://github.com/tommy87166/tablade/blob/main/src/tablade/steps/base.py): `src/tablade/steps/base.py`
- [Cleaning steps](https://github.com/tommy87166/tablade/tree/main/src/tablade/steps): `src/tablade/steps`

### Data processing

- [Input readers](https://github.com/tommy87166/tablade/blob/main/src/tablade/ingest/sources.py): `src/tablade/ingest/sources.py`
- [Encoding support](https://github.com/tommy87166/tablade/blob/main/src/tablade/ingest/encoding.py): `src/tablade/ingest/encoding.py`
- [Excel reader](https://github.com/tommy87166/tablade/blob/main/src/tablade/ingest/excel.py): `src/tablade/ingest/excel.py`
- [ZIP text reader](https://github.com/tommy87166/tablade/blob/main/src/tablade/ingest/zip_lines.py): `src/tablade/ingest/zip_lines.py`
- [Recipe engine](https://github.com/tommy87166/tablade/blob/main/src/tablade/engine/run.py): `src/tablade/engine/run.py`

### Outputs and integrations

- [Stage exports](https://github.com/tommy87166/tablade/blob/main/src/tablade/export/outputs.py): `src/tablade/export/outputs.py`
- [Run manifest](https://github.com/tommy87166/tablade/blob/main/src/tablade/export/manifest.py): `src/tablade/export/manifest.py`
- [AI recipe skill](https://github.com/tommy87166/tablade/blob/main/src/tablade/skill.py): `src/tablade/skill.py`

### Runtime services

- [Usage status](https://github.com/tommy87166/tablade/blob/main/src/tablade/usage.py): `src/tablade/usage.py`
- [Self-test](https://github.com/tommy87166/tablade/blob/main/src/tablade/selftest.py): `src/tablade/selftest.py`
- [Version check](https://github.com/tommy87166/tablade/blob/main/src/tablade/update.py): `src/tablade/update.py`

### Other components

- **User**
- **CLI user**
- **GitHub**

## Connections

- User → Recipe editor: edits recipe (evidence: `README.md`)
- Recipe editor → JS bridge: calls bridge (evidence: `frontend/src/App.tsx`)
- JS bridge → Desktop API: invokes API (evidence: `frontend/src/bridge.ts`)
- Desktop window → Desktop API: exposes API (evidence: `src/tablade/app.py`)
- CLI user → Command line: runs recipe (evidence: `README.md`)
- Desktop API → Recipe session: manages state (evidence: `src/tablade/api.py`)
- Recipe session → Recipe schema: validates recipes (evidence: `src/tablade/session.py`)
- Recipe schema → Recipe validator: checks recipes (evidence: `src/tablade/recipe/schema.py`)
- Recipe schema → Step registry: builds step models (evidence: `src/tablade/recipe/schema.py`)
- Step registry → Step interface: uses interface (evidence: `src/tablade/steps/registry.py`)
- Cleaning steps → Step registry: registers steps (evidence: `src/tablade/steps/__init__.py`)
- Recipe session → Input readers: loads sources (evidence: `src/tablade/session.py`)
- Input readers → Encoding support: decodes inputs (evidence: `src/tablade/ingest/sources.py`)
- Input readers → Excel reader: reads workbooks (evidence: `src/tablade/ingest/sources.py`)
- Input readers → ZIP text reader: reads ZIP members (evidence: `src/tablade/ingest/sources.py`)
- Recipe session → Recipe engine: runs stages (evidence: `src/tablade/session.py`)
- Recipe engine → Input readers: scans inputs (evidence: `src/tablade/engine/run.py`)
- Recipe engine → Step interface: applies steps (evidence: `src/tablade/engine/run.py`)
- Recipe engine → Stage exports: writes results (evidence: `src/tablade/engine/run.py`)
- Stage exports → Run manifest: records run (evidence: `src/tablade/export/outputs.py`)
- Desktop API → AI recipe skill: provides skill (evidence: `src/tablade/api.py`)
- Desktop API → Self-test: runs checks (evidence: `src/tablade/api.py`)
- Desktop API → Usage status: reports usage (evidence: `src/tablade/api.py`)
- Desktop API → Version check: checks version (evidence: `src/tablade/api.py`)
- Version check → GitHub: checks release (evidence: `README.md`)
