# lapis42/srtgo architecture

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

- Interactive diagram: https://gitdiagram.com/lapis42/srtgo
- Repository: https://github.com/lapis42/srtgo

## Overview

##### Project type & purpose (from README + tree)
This is a **Python package / CLI-style automation tool**: “SRTgo: K-Train (KTX, SRT) Reservation Assistant”. It likely **logs into** Korean rail reservation systems and performs **search + reservation workflows** for **SRT** and **KTX (Korail)**.

There is no “frontend/backend” separation; the architecture is primarily:
- **Library modules** that implement provider-specific API/session logic (SRT vs KTX)
- A **top-level orchestration/CLI entry** that calls those modules
- External dependencies: railway reservation websites/APIs (remote systems)

##### File structure analysis → infer components
Top-level:
- `pyproject.toml`: packaging, dependencies, entry points (often defines console script)
- `.github/workflows/python-publish.yml`: CI/CD pipeline to build & publish to PyPI
- `srtgo/` package:
- `__init__.py`: package exports, versioning, public API
- `srtgo.py`: likely the **main entry/orchestrator** (CLI / main function)
- `srt.py`: **SRT provider** implementation (login/search/reserve)
- `ktx.py`: **KTX provider** implementation (login/search/reserve)
- `srt.py` + `ktx.py` likely encapsulate:
- HTTP session/cookies
- request building
- parsing responses
- domain objects (trips, seats, passengers) or simple dict-based flow

Given the acknowledgments to `SRT` and `korail2`, expect:
- Similar architecture: a provider client class that wraps HTTP endpoints and parsing

- **Local package modules** and their boundaries
- **Control flow**: user → CLI → provider client → remote rail system
- **External systems**: SRT website/API, Korail/KTX website/API
- **Cross-cutting concerns**: authentication, session management, parsing, retry/backoff, captcha/2FA (if applicable), rate limiting (even if not implemented, show where it would live)

“software supply chain” aspect:
- GitHub Actions publishing to PyPI, user installs via pip

##### User-facing layer
- **User / Shell**
- **CLI entrypoint** (from `srtgo/srtgo.py` and/or console script in `pyproject.toml`)
- Responsibilities: parse args/options, choose provider, invoke workflows, print results

##### Domain/workflow orchestration
- **Reservation Orchestrator** (may be inside `srtgo.py`)
- Steps: authenticate → search trains → select train/seat → reserve/pay/confirm (depending on what exists)

##### Provider adapters (core architecture)
- **SRT Adapter/Client** (`srtgo/srt.py`)
- **KTX Adapter/Client** (`srtgo/ktx.py`)
- Auth/session (cookies, tokens)
- Search endpoint calls
- Reservation endpoint calls
- Response parsing / normalization into internal structures

##### External systems
- **SRT reservation system** (web/API)
- **Korail/KTX reservation system** (web/API)

##### Packaging/distribution (optional but valuable)
- **GitHub Actions** (`.github/workflows/python-publish.yml`)
- **PyPI** (distribution)
- **End-user environment** (pip install srtgo)

##### Architectural patterns to highlight (specific to this project)
- **Adapter pattern / provider abstraction**: `srt.py` and `ktx.py` are two adapters for different external systems with similar capabilities.
- **Orchestration layer**: `srtgo.py` likely coordinates flows without embedding provider-specific HTTP details.
- **Boundary to external services**: remote reservation systems are the “system of record”; your code is a client with session/state.

##### “Don’t overthink it” but be detailed: suggested maximum component split
- CLI parsing
- Workflow orchestration
- Provider selection/router
- Provider clients (SRT, KTX)
- HTTP transport/session
- Parser/normalizer
- Output formatting
- CI publish pipeline
- PyPI distribution

- [User]
→ [CLI `srtgo/srtgo.py`]
→ [Orchestrator `srtgo/srtgo.py` or `srtgo.py`]
→ [SRT Client `srtgo/srt.py`] → (HTTPS) → [SRT Reservation System]
→ [KTX Client `srtgo/ktx.py`] → (HTTPS) → [Korail/KTX Reservation System]

**Release pipeline:**
- [GitHub Repo] → [GitHub Actions: python-publish.yml] → [PyPI] → [pip install srtgo] → [User runs CLI]

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Runtime / Component View
    %% =========================
    subgraph "User Environment (Local Machine)"
        U["User / Shell"]:::external

        subgraph "srtgo Python Package"
            INIT["Package Facade (srtgo)"]:::module
            CLI["CLI / Entry & Workflow Orchestrator"]:::module

            subgraph "Provider Adapters (Adapter Pattern)"
                SRT["SRT Provider Client"]:::provider
                KTX["KTX Provider Client"]:::provider

                subgraph "SRT Provider Internals"
                    SRT_AUTH["Auth + Session (cookies/tokens)"]:::internal
                    SRT_SEARCH["Search Requests"]:::internal
                    SRT_RES["Reserve/Confirm Requests"]:::internal
                    SRT_PARSE["Parse/Normalize Responses"]:::internal
                end

                subgraph "KTX Provider Internals"
                    KTX_AUTH["Auth + Session (cookies/tokens)"]:::internal
                    KTX_SEARCH["Search Requests"]:::internal
                    KTX_RES["Reserve/Confirm Requests"]:::internal
                    KTX_PARSE["Parse/Normalize Responses"]:::internal
                end
            end

            OUT["Output Formatting (print results/status)"]:::internal
            XCUT["Cross-cutting: retries/backoff, rate-limiting, error handling"]:::note
        end
    end

    subgraph "Internet / External Services"
        SRT_SYS[("SRT Reservation System (Web/API)")]:::externalSystem
        KTX_SYS[("Korail/KTX Reservation System (Web/API)")]:::externalSystem
    end

    %% Runtime connections (vertical emphasis)
    U -->|"run_CLI_command()"| CLI
    INIT -->|"exports/versioning"| CLI

    CLI -->|"select_provider(SRT/KTX)"| SRT
    CLI -->|"select_provider(SRT/KTX)"| KTX

    CLI -->|"execute_workflow(auth→search→select→reserve)"| XCUT
    XCUT -->|"wrap_calls()"| SRT
    XCUT -->|"wrap_calls()"| KTX

    SRT -->|"login(credentials)"| SRT_AUTH
    SRT -->|"search_trains(query)"| SRT_SEARCH
    SRT -->|"reserve(selected_train)"| SRT_RES
    SRT_SEARCH -->|"parse_results()"| SRT_PARSE
    SRT_RES -->|"parse_confirmation()"| SRT_PARSE

    KTX -->|"login(credentials)"| KTX_AUTH
    KTX -->|"search_trains(query)"| KTX_SEARCH
    KTX -->|"reserve(selected_train)"| KTX_RES
    KTX_SEARCH -->|"parse_results()"| KTX_PARSE
    KTX_RES -->|"parse_confirmation()"| KTX_PARSE

    SRT_AUTH -->|"HTTPS_POST_/login"| SRT_SYS
    SRT_SEARCH -->|"HTTPS_GET_/search"| SRT_SYS
    SRT_RES -->|"HTTPS_POST_/reserve"| SRT_SYS
    SRT_SYS -.->|"HTML/JSON_responses"| SRT_PARSE

    KTX_AUTH -->|"HTTPS_POST_/login"| KTX_SYS
    KTX_SEARCH -->|"HTTPS_GET_/search"| KTX_SYS
    KTX_RES -->|"HTTPS_POST_/reserve"| KTX_SYS
    KTX_SYS -.->|"HTML/JSON_responses"| KTX_PARSE

    SRT_PARSE -.->|"normalized_results/status"| CLI
    KTX_PARSE -.->|"normalized_results/status"| CLI

    CLI -->|"render_output()"| OUT
    OUT -->|"display_confirmation/errors"| U

    %% =========================
    %% Release / Distribution
    %% =========================
    subgraph "Build & Release (Supply Chain)"
        DOC["Project Docs"]:::doc
        BUILD["Build Config (deps, console scripts)"]:::config
        CI["CI/CD Publish Pipeline"]:::cicd
        PYPI[("PyPI Registry")]:::registry
        PIP["User installs via pip"]:::external
    end

    DOC -->|"documents_usage"| U
    BUILD -->|"defines_package+entrypoints"| CI
    CI -->|"build_sdist/wheel"| PYPI
    PYPI -->|"pip_install_srtgo"| PIP
    PIP -->|"installs_package"| INIT
    PIP -->|"installs_console_script"| CLI

    %% =========================
    %% Click Events (from mapping)
    %% =========================
    click CLI "https://github.com/lapis42/srtgo/blob/main/srtgo/srtgo.py"
    click SRT "https://github.com/lapis42/srtgo/blob/main/srtgo/srt.py"
    click KTX "https://github.com/lapis42/srtgo/blob/main/srtgo/ktx.py"
    click INIT "https://github.com/lapis42/srtgo/blob/main/srtgo/__init__.py"
    click BUILD "https://github.com/lapis42/srtgo/blob/main/pyproject.toml"
    click CI "https://github.com/lapis42/srtgo/blob/main/.github/workflows/python-publish.yml"
    click DOC "https://github.com/lapis42/srtgo/blob/main/README.md"

    %% =========================
    %% Styles
    %% =========================
    classDef module fill:#2563EB,stroke:#1E3A8A,color:#FFFFFF,stroke-width:1px
    classDef provider fill:#1D4ED8,stroke:#1E40AF,color:#FFFFFF,stroke-width:1px
    classDef internal fill:#60A5FA,stroke:#1E3A8A,color:#0B1220,stroke-width:1px
    classDef external fill:#94A3B8,stroke:#475569,color:#0B1220,stroke-width:1px
    classDef externalSystem fill:#F59E0B,stroke:#92400E,color:#0B1220,stroke-width:1px
    classDef note fill:#E5E7EB,stroke:#6B7280,color:#111827,stroke-width:1px,stroke-dasharray: 4 4
    classDef cicd fill:#6B7280,stroke:#111827,color:#FFFFFF,stroke-width:1px
    classDef registry fill:#FBBF24,stroke:#92400E,color:#111827,stroke-width:1px
    classDef config fill:#64748B,stroke:#0F172A,color:#FFFFFF,stroke-width:1px
    classDef doc fill:#22C55E,stroke:#166534,color:#052e12,stroke-width:1px
```
