# doseidotio/dosei architecture

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

- Interactive diagram: https://gitdiagram.com/doseidotio/dosei
- Repository: https://github.com/doseidotio/dosei

## Overview

##### Main Components
- CLI Component: Located under the “cli” directory, this binary serves as the primary command-line interface for developers. It provides commands for cluster management, deployment, environment handling, login/logout sessions, token management, etc.
- Proxy Component: Under the “proxy” directory, this application likely handles routing or load balancing, acting as an intermediary between external requests and the doseid backend.
- Proto Module: The “proto” directory holds protocol definitions and generates code (using Protocol Buffers) that standardizes communication between various parts of the system.
- Utility/Library Components: The “util” directory provides common functions or libraries (even wrapping package management) and can be seen as a support module used across the project’s binaries.
- Ancillary/Config & DevOps Files: Files like Dockerfile, docker-compose.yml, Makefile, and CI/CD configurations in “.github/workflows” are important for deployment, testing, and continuous integration but may be represented as supporting infrastructure in the architecture.

##### Relationships and Interactions
- The CLI acts as the frontend “control plane” that developers interact with; it translates user commands into API calls or configuration changes.
- The CLI communicates with the doseid server (backend API) either via local network calls or by invoking specific routines.
- The doseid server manages the core runtime logic and communicates with integrated services such as Docker (for container management) and databases (indicated by the presence of migration scripts and SQLx queries in the doseid directory).
- The proxy handles incoming external requests (possibly Internet traffic) and routes them appropriately to the doseid server. This separation suggests that the proxy could be used to provide a stable public endpoint or enforce security policies.
- The Proto module standardizes communications—both between the CLI and server as well as any internal services—with definitions shared across components.
- Integration modules (e.g., GitHub integration under doseid/src/server/integration/github) indicate that the backend also interacts with external systems, which should be represented as external components or services.

##### Architectural Patterns and Design Principles
- Microservice/Modular Design: The clear separation between CLI, server (doseid), proxy, and shared libraries suggests that each component is independently built and deployed, likely communicating via well-defined interfaces.
- Layered Architecture: The system distinguishes between presentation (CLI), application (doseid server handling APIs, deployments, integrations, etc.), and infrastructure (Docker, databases, proxy routing) layers.
- Local-First Development: The design emphasizes a self-hosted and local testing environment (e.g., docker-compose, local migrations) which should be highlighted.
- Extensibility: The integration points (like GitHub) and proto-based communication show that the system is built to be extended and adapted to additional services or infrastructures.

##### Relevant Technologies and Frameworks
- Programming Language: Rust (entire project built with Rust, as indicated by Cargo.toml files across the components).
- Containerization: Docker (Dockerfile & docker-compose.yml files), suggesting container orchestration while remaining cloud-agnostic.
- Database Migration/Query Management: SQLx (evident from the .sqlx directory in doseid).
- CI/CD Tools: GitHub Actions workflows (with multiple CI scripts such as docker-ci.yml and others).
- Protocol Buffers: Used in the “proto” directory for communication schemas.
- External Integrations: GitHub integration and likely other ecosystem components as documented.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend"
        CLI("Dosei CLI"):::frontend
    end

    %% Backend Core Services
    subgraph "Backend Core"
        SERVER("Dosei Server - API/Runtime"):::backend
        PROXY("Proxy Service"):::backend
        PROTO("Proto API Definitions"):::backend
        UTIL("Utility Library"):::backend
        GITHUB("GitHub Integration"):::external
    end

    %% DevOps & Configuration
    subgraph "DevOps & Config"
        DEPLOY("Deployment Config"):::devopsnode
        DOCKERFILE("Dockerfile"):::devops
        DOCKER_COMPOSE("docker-compose.yml"):::devops
        MAKEFILE("Makefile"):::devops
        CICD("CI/CD Workflows"):::devops
    end

    %% Connections between layers
    CLI -->|"sendsCommands"| SERVER
    SERVER -->|"routesRequests"| PROXY
    SERVER -->|"usesProto"| PROTO
    SERVER -->|"callsUtilities"| UTIL
    SERVER -->|"integratesWith"| GITHUB
    SERVER -->|"triggersDeploy"| DEPLOY
    DEPLOY -->|"definesDockerfile"| DOCKERFILE
    DEPLOY -->|"definesCompose"| DOCKER_COMPOSE
    DEPLOY -->|"definesMakefile"| MAKEFILE
    DEPLOY -->|"definesCICD"| CICD

    %% Click Events for Component Mappings
    click CLI "https://github.com/doseidotio/dosei/tree/main/cli/"
    click SERVER "https://github.com/doseidotio/dosei/tree/main/doseid/src/server/"
    click PROXY "https://github.com/doseidotio/dosei/blob/main/proxy/src/main.rs"
    click PROTO "https://github.com/doseidotio/dosei/blob/main/proto/src/lib.rs"
    click UTIL "https://github.com/doseidotio/dosei/blob/main/util/src/lib.rs"
    click DOCKERFILE "https://github.com/doseidotio/dosei/tree/main/Dockerfile"
    click DOCKER_COMPOSE "https://github.com/doseidotio/dosei/blob/main/docker-compose.yml"
    click MAKEFILE "https://github.com/doseidotio/dosei/tree/main/Makefile"
    click CICD "https://github.com/doseidotio/dosei/tree/main/.github/workflows/"

    %% Styles for different layers
    classDef frontend fill:#f9c2ff,stroke:#333,stroke-width:2px;
    classDef backend fill:#c2f9ff,stroke:#333,stroke-width:2px;
    classDef external fill:#d0f0c0,stroke:#333,stroke-width:2px;
    classDef devops fill:#ffe4b5,stroke:#333,stroke-width:2px;
    classDef devopsnode fill:#ffcc99,stroke:#333,stroke-width:2px;
```
