# yumizu-da/atmacup17 architecture

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

- Interactive diagram: https://gitdiagram.com/yumizu-da/atmacup17
- Repository: https://github.com/yumizu-da/atmacup17

## Overview

##### Main Components
- Docker & Development Environment:
- Dockerfile, compose.yaml, .devcontainer directory, and related configuration files.
- These components ensure that experiments run in a consistent and reproducible environment.
- Experiment Management:
- The “exp” directory holds multiple experiment subdirectories. Each experiment (e.g., “001”, “014”, “015”, etc.) contains:
◦ A “config” folder with YAML configuration files (including subdirectories for models that define specific models like “cb.yaml”, “lgb.yaml”, “bert.yaml”, “gemma.yaml”).
◦ Jupyter notebooks (e.g., “run.ipynb”, “eda.ipynb”) where experiments are executed.
◦ A “src” module housing supporting scripts (e.g., “seed.py”, “groupkfold.py”) to manage reproducibility and experiment-specific logic.
- That the naming and structure are used to manage different experiments and maintain reproducibility.
- Data & Results:
- The “data” directory (with placeholder .gitkeep) is for source data.
- The “results” directory is intended to store outputs from experiments.
- Dependency & Library Management:
- The presence of “pyproject.toml”, “.python-version”, and the use of the “uv” tool (as detailed in the README) indicate that dependency management is handled systematically.
- Library management flow from “uv add/remove” commands syncing with pyproject.toml.

##### Relationships and Interactions
- Docker and Environment:
- Experiment Execution Flow:
- Each experiment directory is completely self-contained: it holds its own configuration, experiment-specific code, and notebooks.
- Dependency Management:
- Role of “uv” syncing the libraries as a preparatory step before running experiments.
- Connection between “pyproject.toml” and other configuration components.

##### Architectural Patterns and Design Principles
- Reproducibility:
- The design emphasizes reproducibility; each experiment encapsulated in its own directory maintains environment-specific configurations (YAML files) and seed settings.
- Modular Experimentation:
- The splitting of experiments into independent directories under “exp” signifies a modular approach to experimentation.
- Containerization:
- Docker ensures consistency. The system is designed such that the environment (via the Docker/compose setup) is decoupled from the experiment specifics.
- Infrastructure as Code:
- The use of configuration files and environment descriptors (.devcontainer, compose.yaml) reflects best practices in managing environment dependencies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Docker/Dev Container Environment
    subgraph "Docker/Dev Container Environment"
        D1["Dockerfile"]:::docker
        D2["compose.yaml"]:::docker
        D3[".devcontainer"]:::docker
    end

    %% Dependency & Library Management
    subgraph "Dependency & Library Management"
        DEP1["pyproject.toml"]:::dependency
        DEP2[".python-version"]:::dependency
        DEP3["uv.lock"]:::dependency
        DEP4["README.md"]:::dependency
    end

    %% Experiment Manager
    subgraph "Experiment Manager"
        EXP_DIR["exp/"]:::experiment
        %% Detailed Experiment 001
        subgraph "exp/001"
            E1_CONFIG["config/"]:::experiment
            E1_NOTE["run.ipynb"]:::experiment
            E1_SRC["src/"]:::experiment
        end
        EXP_000["exp/000"]:::experiment
        EXP_014["exp/014"]:::experiment
        EXP_015["exp/015"]:::experiment
        EXP_016["exp/016"]:::experiment
        EXP_017["exp/017"]:::experiment
    end

    %% Data & Results
    subgraph "Data & Results"
        DATA["data/"]:::data
        RESULTS["results/"]:::data
    end

    %% Connections
    DEP1 -->|"setup"| D1
    D1 -->|"runs_experiments"| EXP_DIR
    EXP_DIR -->|"I/O"| DATA
    EXP_DIR -->|"I/O"| RESULTS

    %% Styles
    classDef docker fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef dependency fill:#FFB6C1,stroke:#000,stroke-width:1px;
    classDef experiment fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef data fill:#FFFF99,stroke:#000,stroke-width:1px;

    %% Click Events
    click D1 "https://github.com/yumizu-da/atmacup17/tree/main/Dockerfile"
    click D2 "https://github.com/yumizu-da/atmacup17/blob/main/compose.yaml"
    click D3 "https://github.com/yumizu-da/atmacup17/tree/main/.devcontainer/"
    click DEP1 "https://github.com/yumizu-da/atmacup17/blob/main/pyproject.toml"
    click DEP2 "https://github.com/yumizu-da/atmacup17/blob/main/.python-version"
    click DEP3 "https://github.com/yumizu-da/atmacup17/blob/main/uv.lock"
    click DEP4 "https://github.com/yumizu-da/atmacup17/blob/main/README.md"
    click EXP_DIR "https://github.com/yumizu-da/atmacup17/tree/main/exp/"
    click E1_CONFIG "https://github.com/yumizu-da/atmacup17/tree/main/exp/001/config/"
    click E1_NOTE "https://github.com/yumizu-da/atmacup17/blob/main/exp/001/run.ipynb"
    click E1_SRC "https://github.com/yumizu-da/atmacup17/tree/main/exp/001/src/"
    click EXP_000 "https://github.com/yumizu-da/atmacup17/tree/main/exp/000"
    click EXP_014 "https://github.com/yumizu-da/atmacup17/tree/main/exp/014"
    click EXP_015 "https://github.com/yumizu-da/atmacup17/tree/main/exp/015"
    click EXP_016 "https://github.com/yumizu-da/atmacup17/tree/main/exp/016"
    click EXP_017 "https://github.com/yumizu-da/atmacup17/tree/main/exp/017"
    click DATA "https://github.com/yumizu-da/atmacup17/tree/main/data/"
    click RESULTS "https://github.com/yumizu-da/atmacup17/tree/main/results/"
```
