# tsoding/sowon architecture

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

- Interactive diagram: https://gitdiagram.com/tsoding/sowon
- Repository: https://github.com/tsoding/sowon

## Overview

##### Main Components
- Application Core (main.c): This is the entry point that initializes SDL2, handles window creation, events (such as key presses for toggling pause, zoom, fullscreen, etc.), and manages the timer modes.
- Graphics and Rendering: Since the project depends on SDL2 and includes image conversion logic, there is a clear separation between the UI rendering (drawing the timer, updating visuals based on mode and key inputs) and the asset preparation code (png2c.c and stb_image.h).
- Timer Logic: The logic to manage ascending, descending, and clock modes can be seen as a dedicated module within the main application. This component handles time calculation and mode-specific behaviors.
- Input and Event Handling: The system listens for keyboard events and maps those events to actions like pause, restart, zoom, and toggling fullscreen.
- Asset Conversion Utility: The png2c.c file is likely used for converting image files (perhaps embedded backgrounds or clock graphics) into a C-friendly format that can be used at runtime.

##### Relationships and Data Flow
- The main application initiates SDL2 subsystems, then calls the asset conversion (if needed during a pre-build stage) to embed image data.
- The Timer Logic passes state information to the Rendering module, which updates the display accordingly.
- User Input is captured and directed to both the Timer Logic and Renderer to update states (pause, restart, adjust zoom).
- The build process (Makefile and build_msvc script) ensures that the proper dependencies (SDL2 and image libraries) are linked during compilation.

##### Architectural Patterns and Principles
- Modularization: Even if the code is contained in a few files, conceptually separate the application into modules such as Input Handling, Timer Engine, Rendering, and Asset Preparation.
- Event-Driven Design: Highlight the SDL2 event loop, which continuously listens for input and updates the system state.
- Cross-Platform Considerations: Note that separate instructions exist for Debian, MacOS, and Windows, indicating that the design accommodates multiple operating systems through conditional build steps.

##### Technologies and Libraries
- SDL2: This is the foundation for graphics rendering and event handling.
- stb_image.h: Provides image loading support needed for the asset conversion.
- Build Tools: Makefile for Unix-like systems and build_msvc.bat for Windows illustrate different build environments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Runtime Components
    subgraph "Runtime Components"
        appEntry["Application Entry (main.c)"]:::runtime
        sdlLoop["SDL Init & Event Loop"]:::runtime
        timerLogic["Timer Logic (Ascend/Descend/Clock Modes)"]:::runtime
        renderEngine["Rendering Engine (SDL2 Driven)"]:::runtime
    end

    %% Build & Asset Tools
    subgraph "Build & Asset Tools"
        buildTools["Build Tools (Makefile, build_msvc.bat)"]:::build
        assetConv["Asset Conversion Utility (png2c.c, stb_image.h)"]:::build
    end

    %% Relationships
    appEntry -->|"initiates"| sdlLoop
    sdlLoop -->|"processesInput"| timerLogic
    sdlLoop -->|"callsRender"| renderEngine
    timerLogic -->|"updatesVisuals"| renderEngine
    buildTools -->|"runsPrebuild"| assetConv
    assetConv -->|"embedsAssets"| renderEngine

    %% Click Events
    click appEntry "https://github.com/tsoding/sowon/blob/master/main.c"
    click assetConv "https://github.com/tsoding/sowon/blob/master/png2c.c"
    click assetConv "https://github.com/tsoding/sowon/blob/master/stb_image.h"
    click buildTools "https://github.com/tsoding/sowon/tree/master/Makefile"
    click buildTools "https://github.com/tsoding/sowon/blob/master/build_msvc.bat"

    %% Styles
    classDef runtime fill:#A7C8F2,stroke:#1f77b4,stroke-width:2px;
    classDef build fill:#C7E9B0,stroke:#537237,stroke-width:2px;
    
    %% Legend (for reference)
    %% Runtime Components: Blue boxes | Build/Asset Tools: Green boxes
```
