# tjbai/ji architecture

> Architecture diagram of the GitHub repository tjbai/ji, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tjbai/ji
- Repository: https://github.com/tjbai/ji

## Overview

##### Main Components

A. Core Components:
- CLI Interface (entry point)
- Storage System
- Task Management Engine
- HTML Generator
- Backlog Manager

B. Data Storage:
- Pages Directory (JSON files)
- Write-Ahead Log (WAL)
- Working Page Pointer
- Backlog Storage (JSONL)

**┌─ User Interface Layer ─────┐**
- CLI Module        │
- ┬───────────────┘
- ↓
**┌─ Business Logic Layer ────┐**
- Task Management Engine   │
- Backlog Manager       │
- ┬───────────────┘
- ↓
**┌─ Data Access Layer ───────┐**
- Storage Manager        │
- HTML Generator         │
- ┬───────────────┘
- ↓
**┌─ Persistence Layer ───────┐**
- Pages (JSON)            │
- WAL (Log Files)         │
- Backlog (JSONL)         │
- ┘

##### Component Details

- Rectangles: Core modules (cli.py, model.py, etc.)

##### Key Relationships

a. Command Flow:
- CLI (cli.py) → Task Management (model.py) → Storage
- CLI → HTML Generator (html.py) → Output

b. Data Flow:
- Working Page (wp) ↔ Pages Directory
- Task Operations → WAL
- Backlog Operations ↔ Backlog File

##### Implementation Details

Relationship between the source files:
- cli.py: Command processing and user interaction
- model.py: Core business logic and data structures
- html.py: HTML generation for visualization
- pretty.py: Output formatting

##### Storage Structure

Hierarchical storage system:
**~/.ji/**
- pages/
- wal/
- working pointer

##### Additional Elements

Annotations for:
- File formats (JSON, JSONL, log files)
- Command categories (task management, backlog operations)
- Data flow direction
- State transitions

##### The backlog management system

This system design should effectively communicate both the high-level architecture and the specific implementation details that make "ji" work as a task/journal management tool.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles and classes
    classDef ui fill:#a8d1f0,stroke:#333
    classDef logic fill:#90EE90,stroke:#333
    classDef storage fill:#FFE4B5,stroke:#333
    classDef file fill:#D3D3D3,stroke:#333
    classDef legend fill:none,stroke:#333

    %% User Interface Layer
    subgraph UI["User Interface Layer"]
        CLI["CLI Interface"]:::ui
    end

    %% Business Logic Layer
    subgraph BL["Business Logic Layer"]
        TME["Task Management Engine"]:::logic
        BM["Backlog Manager"]:::logic
    end

    %% Data Access Layer
    subgraph DAL["Data Access Layer"]
        SM["Storage Manager"]:::logic
        HG["HTML Generator"]:::logic
        OF["Output Formatter"]:::logic
    end

    %% Persistence Layer
    subgraph PL["Persistence Layer"]
        Pages[(Pages JSON)]:::storage
        WAL[(Write-Ahead Log)]:::storage
        Backlog[(Backlog JSONL)]:::storage
        WP[("Working Page<br/>Pointer")]:::storage
    end

    %% Relationships
    CLI --> TME
    CLI --> HG
    TME --> SM
    TME --> BM
    BM --> Backlog
    SM --> Pages
    SM --> WAL
    SM --> WP
    HG --> OF
    OF --> CLI

    %% Legend
    subgraph Legend["Legend"]
        L1["UI Components"]:::ui
        L2["Logic Components"]:::logic
        L3["Storage Components"]:::storage
    end

    %% Click events for component mapping
    click CLI "https://github.com/tjbai/ji/blob/main/src/ji/cli.py"
    click TME "https://github.com/tjbai/ji/blob/main/src/ji/model.py"
    click HG "https://github.com/tjbai/ji/blob/main/src/ji/html.py"
    click OF "https://github.com/tjbai/ji/blob/main/src/ji/pretty.py"
    click SM "https://github.com/tjbai/ji/blob/main/src/ji/model.py"

    %% Layout direction
    direction TB
```
