# tinteam/sn-50 architecture

> Architecture diagram of the GitHub repository tinteam/sn-50, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tinteam/sn-50
- Repository: https://github.com/tinteam/sn-50

## Overview

##### Project Type & Purpose
- SN-50 is an open-source “Fantasy Computer” toolkit written in Rust, organized as a Cargo workspace.
- It consists of three crates:
- tinlib – the core library implementing the console specification (CPU, memory, graphics, input, cartridges, etc.)
- devkit – a CLI tool for building and packaging games (cartridges) using tinlib
- player – a CLI tool (runtime) for loading and running cartridges using tinlib

##### Top‐Level Components
a. Cargo Workspace (root)
b. Crates:
- tinlib (library)
- devkit (CLI “builder”)
- player (CLI “emulator”)
c. External Dependencies & Tools
- Rust/Cargo (build system)
- .cartridge files (artifact format)

##### tinlib Subcomponents
- Cartridge module: chunk, error, pack/unpack
- Machine module: CPU code interpreter, memory/ram/vram, input, screen
- Common utilities: coords, sizes, errors
- Module (optional game maps)

##### Relationships & Data Flows
- devkit → tinlib
– Uses tinlib’s cartridge API to pack code, graphics, sound into `.cartridge`
- player → tinlib
– Uses tinlib’s machine+graphics+input APIs to load and run `.cartridge` at runtime
- User interacts with devkit (CLI) to produce cartridges; interacts with player (CLI) to run them.

##### Architectural Patterns & Principles
- Modular library core (tinlib) with well‐defined public API
- Two thin front-ends (devkit, player) that depend on tinlib
- Separation of concerns:
- tinlib = pure logic + console spec
- devkit = build pipeline
- player = execution loop + I/O

##### Essential Elements Checklist
[ ] All components labeled (tinlib, devkit, player, .cartridge, User)
[ ] Nested modules inside tinlib clearly shown
[ ] Clear note of Rust/Cargo as the build system

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Workspace
    CWorkspace["Cargo Workspace"]:::external

    %% Main Components
    devkitBox["devkit (CLI builder)"]:::cli
    playerBox["player (CLI emulator)"]:::cli
    tinlibBox["tinlib (core library)"]:::library
    cartridge[".cartridge"]:::artifact
    User["User"]:::external

    %% tinlib Subcomponents
    subgraph "tinlib Modules"
        LibRoot["lib.rs"]:::library
        subgraph "Cartridge Module"
            chunk["chunk.rs"]
            errorCartridge["error.rs"]
            modCartridge["mod.rs"]
        end
        subgraph "Machine Module"
            code["code.rs"]
            input["input.rs"]
            memory["memory.rs"]
            ram["ram.rs"]
            vram["vram.rs"]
            screen["screen.rs"]
            modMachine["mod.rs"]
        end
        subgraph "Graphic Module"
            color["color.rs"]
            font["font.rs"]
            glyph["glyph.rs"]
            palette["palette.rs"]
            modGraphic["mod.rs"]
        end
        subgraph "Common Utilities"
            coord["coord.rs"]
            size["size.rs"]
            errorCommon["error.rs"]
            modCommon["mod.rs"]
        end
        subgraph "Map Module"
            modMap["mod.rs"]
        end
        examples["examples/cartridge.rs"]:::library
    end

    %% Relationships
    CWorkspace --> tinlibBox
    CWorkspace --> devkitBox
    CWorkspace --> playerBox

    User -->|"uses CLI"| devkitBox
    User -->|"uses CLI"| playerBox

    devkitBox -->|"uses APIs to build .cartridge"| tinlibBox
    devkitBox -->|"produces .cartridge"| cartridge

    playerBox -->|"uses APIs to run .cartridge"| tinlibBox
    cartridge -->|"input to"| playerBox

    %% Click Events
    click CWorkspace "https://github.com/tinteam/sn-50/blob/main/Cargo.toml"
    click tinlibBox "https://github.com/tinteam/sn-50/blob/main/tinlib/Cargo.toml"
    click LibRoot "https://github.com/tinteam/sn-50/blob/main/tinlib/src/lib.rs"
    click chunk "https://github.com/tinteam/sn-50/blob/main/tinlib/src/cartridge/chunk.rs"
    click errorCartridge "https://github.com/tinteam/sn-50/blob/main/tinlib/src/cartridge/error.rs"
    click modCartridge "https://github.com/tinteam/sn-50/blob/main/tinlib/src/cartridge/mod.rs"
    click code "https://github.com/tinteam/sn-50/blob/main/tinlib/src/machine/code.rs"
    click input "https://github.com/tinteam/sn-50/blob/main/tinlib/src/machine/input.rs"
    click memory "https://github.com/tinteam/sn-50/blob/main/tinlib/src/machine/memory.rs"
    click ram "https://github.com/tinteam/sn-50/blob/main/tinlib/src/machine/ram.rs"
    click vram "https://github.com/tinteam/sn-50/blob/main/tinlib/src/machine/vram.rs"
    click screen "https://github.com/tinteam/sn-50/blob/main/tinlib/src/machine/screen.rs"
    click modMachine "https://github.com/tinteam/sn-50/blob/main/tinlib/src/machine/mod.rs"
    click color "https://github.com/tinteam/sn-50/blob/main/tinlib/src/graphic/color.rs"
    click font "https://github.com/tinteam/sn-50/blob/main/tinlib/src/graphic/font.rs"
    click glyph "https://github.com/tinteam/sn-50/blob/main/tinlib/src/graphic/glyph.rs"
    click palette "https://github.com/tinteam/sn-50/blob/main/tinlib/src/graphic/palette.rs"
    click modGraphic "https://github.com/tinteam/sn-50/blob/main/tinlib/src/graphic/mod.rs"
    click coord "https://github.com/tinteam/sn-50/blob/main/tinlib/src/common/coord.rs"
    click size "https://github.com/tinteam/sn-50/blob/main/tinlib/src/common/size.rs"
    click errorCommon "https://github.com/tinteam/sn-50/blob/main/tinlib/src/common/error.rs"
    click modCommon "https://github.com/tinteam/sn-50/blob/main/tinlib/src/common/mod.rs"
    click modMap "https://github.com/tinteam/sn-50/blob/main/tinlib/src/map/mod.rs"
    click examples "https://github.com/tinteam/sn-50/blob/main/tinlib/examples/cartridge.rs"
    click devkitBox "https://github.com/tinteam/sn-50/blob/main/devkit/Cargo.toml"
    click playerBox "https://github.com/tinteam/sn-50/blob/main/player/Cargo.toml"
    click devkitEntry "https://github.com/tinteam/sn-50/blob/main/devkit/src/main.rs"
    click devkitDocs "https://github.com/tinteam/sn-50/blob/main/devkit/README.md"
    click playerEntry "https://github.com/tinteam/sn-50/blob/main/player/src/main.rs"
    click playerDocs "https://github.com/tinteam/sn-50/blob/main/player/README.md"

    %% Styles
    classDef library fill:#f9f,stroke:#333,stroke-width:1px
    classDef cli fill:#bbf,stroke:#333,stroke-width:1px
    classDef artifact fill:#fb0,stroke:#333,stroke-width:1px
    classDef external fill:#dfd,stroke:#333,stroke-width:1px
```
