# picosh/pico architecture

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

- Interactive diagram: https://gitdiagram.com/picosh/pico
- Repository: https://github.com/picosh/pico

## Overview

##### Main Components
- Clients: End users interact with the system using SSH, rsync, scp, or sftp from their terminals.
- Service Endpoints (Microservices):
– Auth Service: (Located under cmd/auth & pkg/apps/auth) handles user authentication and access.
– Pages Service (pgs): (cmd/pgs, pkg/apps/pgs) enables static site hosting with TLS management.
– Feeds Service: (cmd/feeds, pkg/apps/feeds) processes RSS feed subscription and email notifications.
– Pastes Service: (cmd/pastes, pkg/apps/pastes) supports code snippet uploads.
– Prose Service: (cmd/prose, pkg/apps/prose) powers the blog platform.
– Pipe Service: (cmd/pipe, pkg/apps/pipe) manages authenticated Unix pipes over SSH.
– Pico (and possibly tuns): (cmd/pico, pkg/apps/pico, pkg/tunkit) handles lightweight service tasks and creating secure tunnels.
- Infrastructure Components:
– Reverse Proxy / TLS Termination: The “caddy” folder with multiple Caddyfile variants indicates a Caddy-based proxy used to manage TLS and route incoming requests.
– Docker & Deployment: Dockerfiles at the project root, within the “bouncer” directory, and in “caddy” denote containerization. Additionally, the various docker-compose files (e.g., docker-compose.yml, docker-compose.prod.yml) and CI/CD GitHub workflows show a container-based deployment process.
- Shared Libraries and Utilities:
– “pkg” directory: Houses the shared code (database access, file handling, storage abstractions, SSH utilities, etc.) that support all microservices.
– “scripts”: Contains administrative or migration scripts (database migrations, file-size sync, etc.).
– “sql”: Contains schema and migration SQL files, indicating use of relational databases (notably Postgres as seen in pkg/db/postgres).

##### Relationships and Interactions
- How incoming requests are first handled by the reverse proxy (Caddy) which then dispatches to each specific service container.
- For services that depend on a database (e.g., pgs, prose), illustrate the connection to the database layer which uses Postgres (or other storage backends as abstracted by pkg/db).

##### Architectural Patterns and Technologies
- Microservices Pattern: Each major functionality (auth, pages, feeds, pastes, prose, pipe, etc.) exists as a separate command/service with its own SSH and web interfaces.
- Containerization: Extensive Dockerfile usage across services and utilizing docker-compose for orchestration.
- Reverse Proxy/TLS Termination: The Caddy server configuration files indicate layered handling of web requests with different domain rules.
- Shared Code Libraries: Emphasis on the “pkg” folder reflecting a modular design with shared services such as storage abstraction, SSH command handling, and templating for the web front-ends.
- CI/CD Integration: Built-in configuration files for GitHub Actions to run tests, builds, and deploy through automated workflows.

##### Elements
– Clients → Caddy (reverse proxy/TLS termination) → Specific Service
– Service → Database/Storage (for persistence)
– Service interactions if any exist (e.g., if one service triggers an action in another).
- Configuration dependencies (for instance, Docker setups, GitHub CI/CD workflows) that are critical to the deployment lifecycle.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Clients["Clients (SSH/rsync/scp/sftp)"]
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        Proxy["Reverse Proxy/TLS (Caddy)"]
        Docker["Docker & Deployment"]
    end

    %% Microservices
    subgraph "Microservices"
        Auth["Auth Service"]
        Pages["Pages (pgs) Service"]
        Feeds["Feeds Service"]
        Pastes["Pastes Service"]
        Prose["Prose Service"]
        Pipe["Pipe Service"]
        Pico["Pico/Tuns Service"]
    end

    %% Supporting Services
    subgraph "Supporting Services"
        Shared["Shared Libraries & Utilities"]
        Database["Database (Postgres)"]
    end

    %% Connections
    Clients -->|"ssh/rsync/scp/sftp"| Proxy
    Docker -->|"deploys"| Proxy

    Proxy -->|"routes"| Auth
    Proxy -->|"routes"| Pages
    Proxy -->|"routes"| Feeds
    Proxy -->|"routes"| Pastes
    Proxy -->|"routes"| Prose
    Proxy -->|"routes"| Pipe
    Proxy -->|"routes"| Pico

    Auth ---|"uses"| Shared
    Pages ---|"uses"| Shared
    Feeds ---|"uses"| Shared
    Pastes ---|"uses"| Shared
    Prose ---|"uses"| Shared
    Pipe ---|"uses"| Shared
    Pico ---|"uses"| Shared

    Pages -->|"persists"| Database
    Feeds -->|"persists"| Database
    Prose -->|"persists"| Database

    %% Click Events
    click Clients "https://github.com/picosh/pico/tree/main/pkg/pssh"
    click Clients "https://github.com/picosh/pico/tree/main/pkg/send"

    click Auth "https://github.com/picosh/pico/tree/main/cmd/auth"
    click Auth "https://github.com/picosh/pico/tree/main/pkg/apps/auth"

    click Pages "https://github.com/picosh/pico/tree/main/cmd/pgs"
    click Pages "https://github.com/picosh/pico/tree/main/pkg/apps/pgs"

    click Feeds "https://github.com/picosh/pico/tree/main/cmd/feeds"
    click Feeds "https://github.com/picosh/pico/tree/main/pkg/apps/feeds"

    click Pastes "https://github.com/picosh/pico/tree/main/cmd/pastes"
    click Pastes "https://github.com/picosh/pico/tree/main/pkg/apps/pastes"

    click Prose "https://github.com/picosh/pico/tree/main/cmd/prose"
    click Prose "https://github.com/picosh/pico/tree/main/pkg/apps/prose"

    click Pipe "https://github.com/picosh/pico/tree/main/cmd/pipe"
    click Pipe "https://github.com/picosh/pico/tree/main/pkg/apps/pipe"

    click Pico "https://github.com/picosh/pico/tree/main/cmd/pico"
    click Pico "https://github.com/picosh/pico/tree/main/pkg/apps/pico"
    click Pico "https://github.com/picosh/pico/tree/main/pkg/tunkit"

    click Proxy "https://github.com/picosh/pico/tree/main/caddy"

    click Docker "https://github.com/picosh/pico/tree/main/Dockerfile"
    click Docker "https://github.com/picosh/pico/tree/main/bouncer"
    click Docker "https://github.com/picosh/pico/blob/main/docker-compose.yml"

    click Shared "https://github.com/picosh/pico/tree/main/pkg"
    click Shared "https://github.com/picosh/pico/tree/main/scripts"

    %% Styles
    classDef client fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef proxy fill:#A3E4D7,stroke:#117A65,stroke-width:2px;
    classDef service fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef db fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef infra fill:#E8DAEF,stroke:#7D3C98,stroke-width:2px;

    class Clients client;
    class Proxy proxy;
    class Docker infra;
    class Auth,Pages,Feeds,Pastes,Prose,Pipe,Pico service;
    class Database db;
    class Shared infra;
```
