# cased/skyline architecture

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

- Interactive diagram: https://gitdiagram.com/cased/skyline
- Repository: https://github.com/cased/skyline

## Overview

##### Project Type and Purpose
- **Type**: A single‐process, Python‐based CLI tool (installed via pip).
- **Purpose**: Automate the creation of GitHub Apps via the GitHub App Manifest flow, including one-off webhook setup (using smee.io) and secure credential storage.

##### File Structure
- Top-level scripts: `dev-install.sh`, `install.sh`, `example_config.json`.
- Config: `pyproject.toml` defines packaging; `README.md` explains usage.
- Source tree: `src/skyline/`
- `main.py`: CLI entrypoint
- `smee.py`: local HTTP server and proxy logic for callback
- `templates/`: HTML views for the redirect landing page
- `__init__.py`: package metadata

##### Key Architecture Insights from README
- **Configuration layer**: JSON config file or interactive prompts.
- **Temporary Webhook**: Uses smee.io to forward GitHub’s callback to a locally running HTTP server.
- **GitHub Manifest Flow**: The tool launches a browser session to GitHub’s manifest URL, pre-filled from config.
- **Credential Storage**: Writes `.env` entries and private key files into `.github/`.

##### Main Components and Their Responsibilities
A. CLI Layer
- Parses flags (`--config`, `--org`, etc.)
- Chooses between config file vs. interactive prompts
B. Configuration Module
- Reads/parses JSON config
- Prompts user for missing values
C. GitHub API Client
- Crafts the manifest JSON payload
- Issues API calls to GitHub to register the app
D. Smee Proxy / Local HTTP Server
- Registers a unique smee.io channel
- Runs an embedded HTTP server to catch the callback
- Renders `index.html` / `success.html` on callback
E. Browser Launcher
- Opens the user’s default browser pointing to the GitHub manifest flow URL
F. Credential Storage
- Persists `GITHUB_APP_*` env variables to a `.env` or user-specified file
- Writes the private key to `.github/app-private-key.pem`
G. Templates
- Static HTML used by the local server to display success/failure

##### Relationships & Data Flows
1. **User invokes** the `skyline` CLI.
2. CLI → Configuration Module → loads or prompts config.
3. CLI → Smee Module → requests a new channel & starts HTTP server.
4. CLI → Browser Launcher → opens GitHub App Manifest URL (with pre-filled values).
5. Developer completes GitHub UI flow → GitHub sends webhook callback to smee.io → smee.io forwards to local HTTP server.
6. Local HTTP server → renders `success.html` → signals back to the running CLI process.
7. CLI → GitHub API Client / OAuth handshake (if needed) → retrieves App credentials.
8. CLI → Credential Storage → writes `.env` entries + private key file.

##### Architectural Patterns & Design Principles
- **Modular Single-Process**: Clear separation of concerns (config, HTTP server, API client, templating).
- **Adapter Pattern**: `smee.py` abstracts interaction with smee.io and local HTTP.
- **Template Rendering**: Minimalistic view layer for callback pages (index/success).
- **Idempotent Configuration**: JSON config enables reproducible automation scripts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User Interface
    UserUI(["User"]):::ui
    Browser(["Browser"]):::ui

    %% External Services
    GitHubAPI(["GitHub API"]):::external
    SmeeIO(["smee.io"]):::external

    %% Persistent Storage
    Filesystem[(Credential Store)]:::storage

    subgraph "skyline CLI Tool"
        direction TB
        CLI_Layer(["CLI Layer"]):::internal
        Config_Module(["Configuration Module"]):::internal
        ConfigFile(["example_config.json"]):::storage
        Smee_Module(["Smee Proxy / Local HTTP Server"]):::internal
        Browser_Launcher(["Browser Launcher"]):::internal
        GitHubAPI_Client(["GitHub API Client"]):::internal
        Credential_Storage(["Credential Storage"]):::internal

        subgraph "Templates"
            direction TB
            Index_HTML["index.html"]:::internal
            Success_HTML["success.html"]:::internal
        end
    end

    subgraph "Project Metadata & Scripts"
        direction TB
        Packaging["pyproject.toml"]:::storage
        InstallScript["install.sh"]:::external
        DevInstallScript["dev-install.sh"]:::external
    end

    %% Data Flow
    UserUI -->|"1: invoke CLI"| CLI_Layer
    CLI_Layer -->|"2: load or prompt config"| Config_Module
    Config_Module -->|"file mode"| ConfigFile
    CLI_Layer -->|"3: start webhook server"| Smee_Module
    CLI_Layer -->|"4: launch browser"| Browser_Launcher
    Browser_Launcher --> Browser
    Browser -->|"5: complete manifest flow"| GitHubAPI
    GitHubAPI -->|"forward callback"| SmeeIO
    SmeeIO -->|"short-lived HTTP POST"| Smee_Module
    Smee_Module -->|"6: render views"| Index_HTML
    Smee_Module -->|"6: render views"| Success_HTML
    Smee_Module -->|"signal CLI"| CLI_Layer
    CLI_Layer -->|"7: retrieve credentials"| GitHubAPI_Client
    GitHubAPI_Client -->|"API calls"| GitHubAPI
    CLI_Layer -->|"8: write credentials"| Credential_Storage
    Credential_Storage --> Filesystem

    %% Click Events
    click CLI_Layer "https://github.com/cased/skyline/blob/main/src/skyline/main.py"
    click Smee_Module "https://github.com/cased/skyline/blob/main/src/skyline/smee.py"
    click Index_HTML "https://github.com/cased/skyline/blob/main/src/skyline/templates/index.html"
    click Success_HTML "https://github.com/cased/skyline/blob/main/src/skyline/templates/success.html"
    click ConfigFile "https://github.com/cased/skyline/blob/main/example_config.json"
    click Packaging "https://github.com/cased/skyline/blob/main/pyproject.toml"
    click InstallScript "https://github.com/cased/skyline/blob/main/install.sh"
    click DevInstallScript "https://github.com/cased/skyline/blob/main/dev-install.sh"

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#0066CC,stroke-width:1px
    classDef external fill:#D1F7C4,stroke:#2E8B57,stroke-width:1px
    classDef ui fill:#FFD59E,stroke:#CC8400,stroke-width:1px
    classDef storage fill:#E0E0E0,stroke:#A0A0A0,stroke-width:1px
```
