# opsway-io/backend architecture

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

- Interactive diagram: https://gitdiagram.com/opsway-io/backend
- Repository: https://github.com/opsway-io/backend

## Overview

##### Project type and purpose
- This is a Go-based monorepo for the “opsway” backend. It exposes a REST API (`cmd/api.go`), a probe runner (`cmd/prober.go`), and CLI commands (`cmd/seed.go`, etc.) for data seeding.
- Purpose: manage uptime monitoring (“probes”), incidents, maintenance windows, reporting, teams/users, billing, authentication, and notifications.

##### File structure
- Top-level executables under `cmd/`: API server, probe runner, CLI seeds.
- `internal/`: core business logic, broken out by domain (`authentication`, `billing`, `changelog`, `check`, `incident`, `maintenance`, `monitor`, `report`, `team`, `user`).
- `internal/connectors/`: database/queue clients for Postgres, ClickHouse, Redis.
- `internal/rest/`: HTTP layer—controllers, handlers, middleware.
- `internal/notification/email/`: email-templating and senders.
- `internal/probes/http/`: HTTP probe asserters.
- `internal/event/`: event publishing service.
- `internal/storage/`: object storage abstraction.
- Configuration and Docker artefacts in root (`Dockerfile`, `docker-compose.yaml`, `.github/workflows/`).

##### Extract key architecture insights from README
- Entirely dockerized, hot-reloaded Go code, automatic migrations.
- External dependencies spun up via Docker-Compose (Postgres, Redis, ClickHouse, SendGrid or SMTP).

##### Main components & interactions
a. Components
1. API Server (REST)
2. Probe Runner (background worker)
3. CLI Seeder
4. Domain Services (Authentication, Billing, Monitor, Incident, etc.)
5. Repositories / Connectors (Postgres, ClickHouse, Redis)
6. Event Bus / Publisher
7. Notification Service (Email via Console or SendGrid)
8. Object Storage (S3-compatible or similar)
9. External Clients: Users → HTTP(S), SMTP/SendGrid
10. Docker-Compose network

b. Relationships & data flow
- User → HTTP REST API → Controllers → Handlers → Services → Repositories → Databases
- Services publish domain events to Event Bus → Event Service subscribers (e.g., Notification)
- Probe Runner reads monitor definitions from DB → executes checks via `internal/probes` → writes results to ClickHouse (for metrics) and Postgres (for status) → may trigger incidents/events
- Notification Service subscribes to events → renders templates → sends emails via SMTP/SendGrid
- Object Storage used by API for avatars or report exports
- CLI Seeder writes seed data directly to DB via repositories

c. Architectural patterns & principles
- Layered (Controller → Service → Repository → Connector)
- Domain-driven: each domain has its own package under `internal/`
- Single binary for API, separate binary for worker (prober)
- Event-driven notifications
- Infrastructure as code via Docker Compose

d. Technologies & frameworks
- Go modules, Gin or standard net/http (in `internal/rest/server.go`)
- PostgreSQL (primary OLTP)
- ClickHouse (time-series metrics storage)
- Redis (caching, locks, rate limits)
- SendGrid or SMTP for email
- Docker, Docker Compose, GitHub Actions

2. Inside the API Server block, subdivide into: REST Controllers, Handlers, Service Layer, Repositories, Connectors.
3. Inside the Probe Runner block, show Monitor definitions → Probe Engine → Results → Storage (ClickHouse & Postgres)
4. Event Bus between Service Layer and Notification Service.
5. Notification Service rendering templates and sending via SMTP/SendGrid.
6. Technologies at each boundary (e.g., “Postgres via internal/connectors/postgres/client.go”).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Actors
    Users["End Users (HTTP)"]:::external
    SMTP["SMTP / SendGrid"]:::external

    %% Docker Compose Network
    subgraph "Docker-Compose Network"
        direction TB
        %% Application Components
        subgraph "API Server" 
            direction TB
            APIExecutable["cmd/api.go"]:::app
            RESTServer["internal/rest/server.go"]:::app
            Controllers["internal/rest/controllers/"]:::app
        end
        subgraph "Probe Runner"
            direction TB
            ProbeExecutable["cmd/prober.go"]:::app
            ProbeService["internal/probes/http/service.go"]:::app
            ProbeResult["internal/probes/http/result.go"]:::app
            Asserters["internal/probes/http/asserter/"]:::app
        end
        subgraph "CLI Seeder"["CLI Seeder (one-off)"]
            direction TB
            SeederExec["cmd/seed.go"]:::app
            SeedMonitors["seeds/monitors.go"]:::app
            SeedTeams["seeds/teams_and_users.go"]:::app
            SeedOpsway["seeds/team_opsway.go"]:::app
        end

        %% Data Stores & Services
        Postgres["PostgreSQL"]:::datastore
        ClickHouse["ClickHouse"]:::datastore
        Redis["Redis"]:::datastore
        ObjectStorage["Object Storage"]:::datastore
        EventBus["Event Bus"]:::datastore
        Notification["Notification Service"]:::app
    end

    %% Interactions
    Users -->|"HTTP REST"| APIExecutable
    APIExecutable -->|"loads"| RESTServer
    RESTServer -->|"routes to"| Controllers
    Controllers -->|"calls services"| EventBus
    Controllers -->|"SQL"| Postgres
    Controllers -->|"Cache"| Redis
    Controllers -->|"S3 API"| ObjectStorage

    ProbeExecutable -->|"loads"| ProbeService
    ProbeService -->|"executes checks"| Asserters
    ProbeService -->|"writes status"| Postgres
    ProbeService -->|"writes metrics"| ClickHouse
    ProbeService -->|"publishes events"| EventBus

    SeederExec -->|"writes seed data"| Postgres

    EventBus -->|"subscribes"| Notification
    Notification -->|"sends email"| SMTP
    Notification -->|"templates"| internal_templates["internal/notification/email/templates/"]:::app

    %% Click Events
    click APIExecutable "https://github.com/opsway-io/backend/blob/master/cmd/api.go"
    click RESTServer "https://github.com/opsway-io/backend/blob/master/internal/rest/server.go"
    click Controllers "https://github.com/opsway-io/backend/tree/master/internal/rest/controllers/"
    click ProbeExecutable "https://github.com/opsway-io/backend/blob/master/cmd/prober.go"
    click ProbeService "https://github.com/opsway-io/backend/blob/master/internal/probes/http/service.go"
    click ProbeResult "https://github.com/opsway-io/backend/blob/master/internal/probes/http/result.go"
    click Asserters "https://github.com/opsway-io/backend/tree/master/internal/probes/http/asserter/"
    click SeederExec "https://github.com/opsway-io/backend/blob/master/cmd/seed.go"
    click SeedMonitors "https://github.com/opsway-io/backend/blob/master/seeds/monitors.go"
    click SeedTeams "https://github.com/opsway-io/backend/blob/master/seeds/teams_and_users.go"
    click SeedOpsway "https://github.com/opsway-io/backend/blob/master/seeds/team_opsway.go"

    %% Classes
    classDef app fill:#DDEEFF,stroke:#0033CC
    classDef datastore fill:#CCFFCC,stroke:#009900
    classDef external fill:#FFE0B2,stroke:#FF8000
```
