# thumuss/utpm architecture

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

- Interactive diagram: https://gitdiagram.com/thumuss/utpm
- Repository: https://github.com/thumuss/utpm

## Overview

##### Main Components

a) Core Components:
- CLI Interface (Entry Point)
- Command Processor
- Package Manager Core
- File System Interface
- State Management
- Configuration Handler

b) Command Modules:
- Workspace Management
- Package Management
- Generation Utilities

**┌─ User Interface Layer ─────────────────────┐**
- CLI Interface (src/main.rs)                │
- ┬─────────────────────────┘
- ↓
**┌─ Command Layer ──────────────────────────────┐**
- ┌─ Workspace Commands ─┐ ┌─ Package Commands ┐│
- Create            │ │ - List            ││
- Link             │ │ - Tree            ││
- Install          │ │ - Unlink          ││
- Add              │ │ - Bulk Delete     ││
- ┘ └──────────────────┘ │
- ┬──────────────────────────┘
- ↓
**┌─ Core Layer ────────────────────────────────┐**
- ┌─ Utils ──────────┐ ┌─ State Management ─┐ │
- Paths          │ │ - Package State    │ │
- Specs          │ │ - Config State     │ │
- Macros         │ └──────────────────┘ │ │
- ┘                        │
- ┬──────────────────────────┘
- ↓
**┌─ External Interface Layer ──────────────────┐**
- File System                              │
- Remote Package Registry                  │
- Typst Universe Integration              │
- ┘

##### Important Elements to Highlight

a) Data Flow:
- Command flow from CLI to specific command handlers
- Package management operations
- State management interactions

b) Key Interactions:
- Package creation and management workflow
- Dependency resolution process
- Remote package registry communication

##### Implementation Details to Note

- Command structure follows a modular approach (src/commands/)
- Utility functions are centralized (src/utils/)
- State management is handled separately (src/utils/state.rs)
- CI/CD integration exists (.github/workflows/)

This design reflects the current state of UTPM while allowing for the planned features mentioned in the README, such as automated publication to Typst Universe.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles
    classDef ui fill:#3498db,stroke:#2980b9,color:white
    classDef command fill:#2ecc71,stroke:#27ae60,color:white
    classDef core fill:#f1c40f,stroke:#f39c12,color:black
    classDef external fill:#95a5a6,stroke:#7f8c8d,color:white

    %% User Interface Layer
    CLI[CLI Interface]:::ui
    click CLI "https://github.com/Thumuss/utpm/blob/dev/src/main.rs"

    %% Command Layer
    subgraph CommandLayer[Command Layer]
        CmdHandler[Command Handler]:::command
        click CmdHandler "https://github.com/Thumuss/utpm/blob/dev/src/commands.rs"

        subgraph WorkspaceCommands[Workspace Commands]
            Create[Create]:::command
            Link[Link]:::command
            Install[Install]:::command
            Add[Add]:::command
        end

        subgraph PackageCommands[Package Commands]
            List[List]:::command
            Tree[Tree]:::command
            Unlink[Unlink]:::command
            BulkDelete["Bulk Delete"]:::command
        end
    end

    %% Core Layer
    subgraph CoreLayer[Core Layer]
        subgraph Utils[Utilities]
            Paths[Path Management]:::core
            Specs["Package Specs"]:::core
            Macros[Macro Utilities]:::core
        end

        subgraph State[State Management]
            PkgState["Package State"]:::core
            ConfigState["Config State"]:::core
        end
    end

    %% External Interface Layer
    subgraph ExternalLayer[External Interface Layer]
        FS["File System"]:::external
        Registry["Remote Package Registry"]:::external
        Universe["Typst Universe"]:::external
    end

    %% Click Events for Components
    click Create "https://github.com/Thumuss/utpm/blob/dev/src/commands/create.rs"
    click Link "https://github.com/Thumuss/utpm/blob/dev/src/commands/link.rs"
    click Install "https://github.com/Thumuss/utpm/blob/dev/src/commands/install.rs"
    click Add "https://github.com/Thumuss/utpm/blob/dev/src/commands/add.rs"
    click List "https://github.com/Thumuss/utpm/blob/dev/src/commands/list.rs"
    click Tree "https://github.com/Thumuss/utpm/blob/dev/src/commands/tree.rs"
    click Unlink "https://github.com/Thumuss/utpm/blob/dev/src/commands/unlink.rs"
    click BulkDelete "https://github.com/Thumuss/utpm/blob/dev/src/commands/bulk_delete.rs"
    click Paths "https://github.com/Thumuss/utpm/blob/dev/src/utils/paths.rs"
    click Specs "https://github.com/Thumuss/utpm/blob/dev/src/utils/specs.rs"
    click Macros "https://github.com/Thumuss/utpm/blob/dev/src/utils/macros.rs"
    click PkgState "https://github.com/Thumuss/utpm/blob/dev/src/utils/state.rs"
    click ConfigState "https://github.com/Thumuss/utpm/blob/dev/src/utils/state.rs"

    %% Connections
    CLI --> CmdHandler
    CmdHandler --> WorkspaceCommands
    CmdHandler --> PackageCommands
    WorkspaceCommands --> CoreLayer
    PackageCommands --> CoreLayer
    CoreLayer --> ExternalLayer

    %% Legend
    subgraph Legend
        UI[User Interface]:::ui
        CMD[Commands]:::command
        CORE[Core Components]:::core
        EXT[External Systems]:::external
    end
```
