# zendesk/samson architecture

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

- Interactive diagram: https://gitdiagram.com/zendesk/samson
- Repository: https://github.com/zendesk/samson

## Overview

##### Main Components Identification

The system should be represented with these core components:

a. Web Application Layer
- Rails application (app/ directory)
- Asset pipeline (app/assets/)
- Views and templates (app/views/)
- Controllers for different functionalities (app/controllers/)

b. Data Layer
- Database (supports MySQL, PostgreSQL, or SQLite)
- Model layer (app/models/)
- Secrets management (lib/samson/secrets/)

c. Integration Layer
- Multiple plugin systems (plugins/ directory)
- External service integrations (GitHub, GitLab, Jenkins, etc.)
- WebSocket channels for real-time updates (app/channels/)

d. Deployment Engine
- Git repository management
- Job execution system
- Deploy orchestration
- Kubernetes integration (if enabled)

**[Web Interface] → [Application Core] → [Database]**
- ↕               ↕                   ↕
**[WebSocket] ← [Event System] → [Job Queue]**

**[External Services] → [Plugin System] → [Core]**
- GitHub            Kubernetes         ↕
- GitLab            Jenkins        [Secrets]
- etc.              etc.

**[Git Repo] → [Build] → [Deploy] → [Monitor]**
- ↓         ↓          ↓
- [Artifacts] [Stages] [Notifications]

##### Key Relationships

- User authentication flow through OAuth providers
- Deploy workflow from trigger to completion
- Plugin interaction with core systems
- Real-time updates through WebSocket channels
- Secret management flow

##### Important Details

- Security boundaries (authentication/authorization)
- Database interactions
- Plugin extension points
- WebSocket communication paths
- Deployment state transitions

##### Specific Implementation Notes

- Plugin architecture as modular components
- Real-time deployment monitoring system
- Role-based access control system
- Multi-stage deployment capability
- Integration points with CI/CD systems

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Web_Layer
        WebInterface["Web Interface"]:::frontend
        AssetPipeline["Asset Pipeline"]:::frontend
        Views["Views"]:::frontend
        Controllers["Controllers"]:::core
    end

    subgraph Core_Layer
        AppCore["Application Core"]:::core
        EventSystem["Event System"]:::core
        JobQueue["Job Queue"]:::core
        WebSocket["WebSocket System"]:::realtime
    end

    subgraph Data_Layer
        Database[(Database)]:::database
        Models["Models"]:::data
        SecretsManager["Secrets Manager"]:::security
    end

    subgraph Integration_Layer
        PluginSystem["Plugin System"]:::plugin
        ExternalServices["External Services"]:::external
        Webhooks["Webhooks"]:::integration
    end

    subgraph Security
        Auth["Authentication"]:::security
        AccessControl["Authorization"]:::security
    end

    subgraph Deployment_Engine
        GitRepo["Git Repository"]:::deploy
        DeployOrch["Deploy Orchestration"]:::deploy
        JobExec["Job Execution"]:::deploy
        K8s["Kubernetes"]:::deploy
    end

    subgraph RealTime_Updates
        WSConnection["WebSocket Connection"]:::realtime
        DeployNotif["Deploy Notifications"]:::realtime
        JobOutputs["Job Outputs"]:::realtime
    end

    %% Relationships
    WebInterface --> Controllers
    Controllers --> AppCore
    AppCore --> Models
    Models --> Database
    AppCore --> EventSystem
    EventSystem --> JobQueue
    EventSystem --> WebSocket
    PluginSystem --> AppCore
    ExternalServices --> PluginSystem
    Auth --> AppCore
    AccessControl --> AppCore
    GitRepo --> DeployOrch
    DeployOrch --> JobExec
    JobExec --> K8s
    WSConnection --> DeployNotif
    WSConnection --> JobOutputs
    SecretsManager --> AppCore
    Webhooks --> AppCore

    %% Click Events
    click Controllers "https://github.com/zendesk/samson/tree/master/app/controllers/"
    click AssetPipeline "https://github.com/zendesk/samson/tree/master/app/assets/"
    click Views "https://github.com/zendesk/samson/tree/master/app/views/"
    click Models "https://github.com/zendesk/samson/tree/master/app/models/"
    click SecretsManager "https://github.com/zendesk/samson/tree/master/lib/samson/secrets/"
    click PluginSystem "https://github.com/zendesk/samson/tree/master/plugins/"
    click Webhooks "https://github.com/zendesk/samson/blob/master/app/controllers/webhooks_controller.rb"
    click DeployOrch "https://github.com/zendesk/samson/blob/master/app/models/deploy.rb"
    click JobExec "https://github.com/zendesk/samson/blob/master/app/models/job_execution.rb"
    click GitRepo "https://github.com/zendesk/samson/blob/master/app/models/git_repository.rb"
    click K8s "https://github.com/zendesk/samson/tree/master/plugins/kubernetes/"
    click Auth "https://github.com/zendesk/samson/blob/master/app/controllers/sessions_controller.rb"
    click AccessControl "https://github.com/zendesk/samson/blob/master/app/models/access_control.rb"
    click WSConnection "https://github.com/zendesk/samson/blob/master/app/channels/application_cable/connection.rb"
    click DeployNotif "https://github.com/zendesk/samson/blob/master/app/channels/deploy_notifications_channel.rb"
    click JobOutputs "https://github.com/zendesk/samson/blob/master/app/channels/job_outputs_channel.rb"

    %% Styling
    classDef core fill:#2374ab
    classDef frontend fill:#57a773
    classDef database fill:#484848
    classDef data fill:#89a7c2
    classDef security fill:#ffd151
    classDef deploy fill:#d64933
    classDef plugin fill:#7a306c
    classDef external fill:#9b9b9b
    classDef integration fill:#a8d0db
    classDef realtime fill:#28afb0
```
