# jadijadi/for-the-win-farsi architecture

> Architecture diagram of the GitHub repository jadijadi/for-the-win-farsi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jadijadi/for-the-win-farsi
- Repository: https://github.com/jadijadi/for-the-win-farsi

## Overview

##### Project type & purpose (what you’re diagramming)
This repo is **not a software system** in the typical sense (no runtime, services, build artifacts, or code). It’s a **content/translation repository** that:
- Hosts the **canonical upstream HTML** of Cory Doctorow’s *For the Win* (`Cory_Doctorow_-_For_the_Win.htm`)
- Stores **extracted chapter-per-file Markdown** in `chapters/` (source English text / extraction output)
- Stores **Persian (Farsi) translation** chapter-per-file Markdown in `chapters_fa/` (`*.rtl.md`, indicating right-to-left formatting)

So the “architecture” is essentially a **content pipeline + repository structure + licensing/attribution constraints**.

- **Artifacts** (HTML, MD chapters, RTL MD translations, LICENSE/README)
- **Processes** (extraction/splitting, translation, editing/review, publishing/export if applicable)
- **Actors** (translator/LLM, editor/reviewer)
- **External dependency** (upstream canonical source URL and CC license)

##### File structure analysis (components you must reflect)
Top-level:
- `Cory_Doctorow_-_For_the_Win.htm`: upstream canonical HTML snapshot (source-of-truth content)
- `chapters/`: `chapter_01.md` … `chapter_63.md`
→ indicates a deterministic “split into chapters” step occurred or is intended
- `chapters_fa/`: `chapter_01.rtl.md` … `chapter_11.rtl.md` (so far)
→ translation is WIP; only first N chapters translated
- `LICENSE`: CC BY-NC-SA 3.0 license text
- `README.md`: workflow + attribution + layout

Architecturally, this implies a **one-way content derivation chain**:
Upstream HTML → extracted English chapters → translated Persian chapters (RTL)

…and a governance layer:
License terms constrain all derivatives.

##### README insights to incorporate
From the README, explicitly model:
- Upstream / canonical HTML location (external system)
- License and translation rights (constraints)
- Workflow roles:
- initial translation aided by an LLM
- editing/review by Jadi Mirmirani
- “WIP” nature (partial translation coverage)

##### `Upstream canonical HTML (URL)` → `Cory_Doctorow_-_For_the_Win.htm`
2. `Cory_Doctorow_-_For_the_Win.htm` → *(process)* `Extract/Split` → `chapters/chapter_01..63.md`
3. `chapters/chapter_XX.md` → *(process)* `Translate (LLM-assisted)` → `chapters_fa/chapter_XX.rtl.md`
4. `chapters_fa/*.rtl.md` ↔ *(process)* `Human edit/review/QC` (bidirectional to show iterative edits)

**WIP gap**:
- English chapters exist for 01–63
- Persian chapters exist for 01–11 only

##### c) Important patterns/principles
- **Source of truth**: upstream canonical HTML
- **Derived artifacts**: chapter Markdown are generated/extracted, translation is derived from source chapters
- **Idempotent/traceable segmentation**: chapter-per-file naming convention (`chapter_XX`)
- **Governance by license**: CC BY-NC-SA ShareAlike constraint applies to derivatives
- **Human-in-the-loop**: LLM-assisted translation followed by editorial review

##### d) Relevant technologies/libraries
- Formats: HTML, Markdown, RTL Markdown
- Tooling (implicit): Git/GitHub for collaboration, optional LLM tooling for translation

- **External**: Upstream Canonical HTML (URL)
↓
- **Repo**: `Cory_Doctorow_-_For_the_Win.htm` (snapshot)
↓ (Process: Extract/Split)
- **Repo**: `chapters/` (EN Markdown chapters 01–63)
↓ (Process: Translate, LLM-assisted)
- **Repo**: `chapters_fa/` (FA RTL Markdown chapters 01–11, WIP)
↺ (Process: Human edit/review/QC)

Side overlay:
- `LICENSE` (CC BY-NC-SA 3.0) → applies to all repo artifacts and any published outputs
- `README.md` → documents attribution + workflow

This captures “as many components as possible” without inventing infrastructure that doesn’t exist.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% ============ EXTERNAL ============
  subgraph "External (Upstream)"
    UpstreamURL["Upstream canonical HTML (craphound.com/ftw/...)"]:::external
  end

  %% ============ REPOSITORY ============
  subgraph "Git Repository (Content + Translation)"
    direction TB

    subgraph "Source Artifact"
      HTMLSnapshot["Upstream HTML snapshot\n(Cory_Doctorow_-_For_the_Win.htm)"]:::artifact
    end

    subgraph "Derived Artifacts"
      direction TB

      ChaptersEN["English chapters (Markdown)\nchapters/chapter_01.md … chapter_63.md"]:::artifact
      ChaptersFA["Persian translation (RTL Markdown) — WIP\nchapters_fa/chapter_01.rtl.md … chapter_11.rtl.md"]:::artifactWip
    end

    subgraph "Governance & Documentation"
      direction TB
      License["LICENSE\nCC BY-NC-SA 3.0"]:::constraint
      Readme["README.md\nWorkflow + attribution"]:::doc
    end
  end

  %% ============ WORKFLOW / PIPELINE ============
  subgraph "Content Workflow (manual / external tooling; scripts not in repo)"
    direction TB
    Fetch["Fetch/Update upstream HTML"]:::process
    Split["Extract/Split HTML → chapter Markdown"]:::process
    Translate["Translate EN MD → FA RTL MD\n(LLM-assisted)"]:::process
    Review["Human edit/review/QC\n(iterative)"]:::process
    Publish["Publish/Export\n(website/ebook/PDF) — optional"]:::processOptional
  end

  %% ============ ACTORS ============
  subgraph "Actors"
    direction TB
    Maintainer["Maintainer/Contributor\n(Git)"]:::actor
    Translator["Translator\n(LLM-assisted)"]:::actor
    Editor["Editor/Reviewer (Human)\n(Jadi Mirmirani)"]:::actor
  end

  %% ============ FLOWS (VERTICAL) ============
  UpstreamURL -->|"canonical_source"| Fetch
  Fetch -->|"updates"| HTMLSnapshot

  HTMLSnapshot -->|"input"| Split
  Split -->|"generates"| ChaptersEN

  ChaptersEN -->|"input"| Translate
  Translate -->|"creates"| ChaptersFA

  ChaptersFA -->|"edit_cycle"| Review
  Review -->|"changes"| ChaptersFA

  ChaptersFA -->|"export"| Publish

  %% ============ GOVERNANCE / DOC RELATIONSHIPS ============
  License -->|"constrains_derivatives"| HTMLSnapshot
  License -->|"constrains_derivatives"| ChaptersEN
  License -->|"constrains_derivatives"| ChaptersFA
  License -->|"constrains_derivatives"| Publish

  Readme -->|"documents_source+attribution"| UpstreamURL
  Readme -->|"documents_workflow"| Fetch
  Readme -->|"documents_workflow"| Split
  Readme -->|"documents_workflow"| Translate
  Readme -->|"documents_workflow"| Review

  %% ============ ACTOR PARTICIPATION ============
  Maintainer -->|"maintains_repo"| HTMLSnapshot
  Maintainer -->|"maintains_repo"| ChaptersEN
  Maintainer -->|"maintains_repo"| ChaptersFA
  Maintainer -->|"maintains_repo"| Readme
  Maintainer -->|"maintains_repo"| License

  Translator -->|"performs"| Translate
  Editor -->|"performs"| Review
  Maintainer -->|"initiates"| Fetch
  Maintainer -->|"runs"| Split

  %% ============ CLICK EVENTS (from component mapping) ============
  click HTMLSnapshot "https://github.com/jadijadi/for-the-win-farsi/blob/main/Cory_Doctorow_-_For_the_Win.htm"
  click ChaptersEN "https://github.com/jadijadi/for-the-win-farsi/tree/main/chapters/"
  click ChaptersFA "https://github.com/jadijadi/for-the-win-farsi/tree/main/chapters_fa/"
  click License "https://github.com/jadijadi/for-the-win-farsi/tree/main/LICENSE"
  click Readme "https://github.com/jadijadi/for-the-win-farsi/blob/main/README.md"

  %% Representative file-level click targets (examples within the mapped ranges)
  click ChaptersEN "https://github.com/jadijadi/for-the-win-farsi/blob/main/chapters/chapter_01.md"
  click ChaptersFA "https://github.com/jadijadi/for-the-win-farsi/blob/main/chapters_fa/chapter_01.rtl.md"

  %% ============ STYLES ============
  classDef external fill:#E8F1FF,stroke:#2B6CB0,stroke-width:2px,color:#0B1F44
  classDef artifact fill:#E9FCE9,stroke:#2F855A,stroke-width:2px,color:#12351F
  classDef artifactWip fill:#F0FFF4,stroke:#38A169,stroke-width:2px,stroke-dasharray:6 4,color:#12351F
  classDef process fill:#FFF7E6,stroke:#B7791F,stroke-width:2px,color:#3B2A0A
  classDef processOptional fill:#FFFBF0,stroke:#B7791F,stroke-width:2px,stroke-dasharray:4 4,color:#3B2A0A
  classDef actor fill:#F4E8FF,stroke:#6B46C1,stroke-width:2px,color:#23104A
  classDef constraint fill:#FFECEC,stroke:#C53030,stroke-width:2px,color:#4A0C0C
  classDef doc fill:#EEF2F7,stroke:#4A5568,stroke-width:2px,color:#1A202C
```
