# sumitk99/cloudrunr architecture

> Architecture diagram of the GitHub repository sumitk99/cloudrunr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sumitk99/cloudrunr
- Repository: https://github.com/sumitk99/cloudrunr

## Overview

1. **Overall shape**
   CloudRunr is split into four runtime services plus edge/cloud infrastructure: an **API server** for control-plane operations, a **build server** for per-deployment build execution, a **log consumer** for persistence of streaming logs, and a **proxy server** for serving deployed apps by subdomain. The root `CloudFrontFunction.js` suggests an additional edge rewrite/routing layer in front of the proxy/static assets.

2. **API server = control plane**
   `api-server` is the main backend entrypoint. Its `handler`, `service`, `repository`, `middleware`, and `routes` packages show a classic layered Go API. It owns authentication, project CRUD, deployment orchestration, and log retrieval endpoints. The presence of `auth_middleware.go`, `validator.go`, and `auth_service.go` indicates JWT-based auth plus request validation before hitting business logic.

3. **Persistence boundary**
   The API server talks to **PostgreSQL** for users/projects/deployments and to **TimescaleDB** for deployment logs. The README’s schema maps directly to the code structure: user and project metadata live in relational tables, while `log_statements` is a time-series table keyed by deployment/project and timestamp. This is the primary data boundary between control metadata and append-only operational logs.

4. **Deployment orchestration**
   The API server does not build apps itself; it triggers the build pipeline by starting an ECS task. `api-server/internal/server/kafka_server.go` and the AWS-related env vars in the README point to ECS integration and message-passing setup. In architecture terms, the API server is the coordinator that creates deployment records, launches a build job, and later serves log/deployment status queries.

5. **Build server = ephemeral worker**
   `build-server` is a containerized worker used for one deployment at a time. Its `script`, `helper`, `server`, and shell entrypoint files indicate it clones the GitHub repo, installs dependencies, runs framework-specific builds, and publishes the generated static output. README config shows it is parameterized by `GIT_REPOSITORY_URL`, `PROJECT_ID`, `FRAMEWORK`, and `DEPLOYMENT_ID`, which makes it a job runner rather than a long-lived API.

6. **Artifact publishing**
   The build server uploads built assets to **AWS S3** under a project-specific path. That creates the serving boundary for deployed frontend apps: source code is pulled from GitHub, transformed in the build container, then written as static output to S3 for distribution. The README’s S3 isolation by `project_id` is the key multi-tenant storage rule.

7. **Real-time log pipeline**
   Build logs are streamed out of the build server through **Kafka**. This decouples live log generation from durable storage and lets the UI/API read logs without blocking the build. The build server emits, Kafka transports, and a separate consumer persists the records.

8. **Log consumer = sink to TimescaleDB**
   `log-consumer/main.go` is a dedicated Kafka consumer whose job is to ingest build/deployment log events and write them to TimescaleDB. This service is the durability layer for logs, supporting offset-based log retrieval and time-ordered reads. It is intentionally separate from the API server so log throughput does not affect user-facing request latency.

9. **Proxy server = runtime app serving**
   `proxy-server` is the serving plane for deployed applications. Its minimal structure suggests it mainly performs request middleware/routing based on subdomain or host header, then forwards traffic to the correct project content. In combination with CloudFront and S3, this gives each project its own externally reachable subdomain without a separate app runtime per tenant.

10. **Edge routing**
   `CloudFrontFunction.js` indicates request rewriting or host/path normalization at the CDN edge. That is the outermost routing layer, likely translating wildcard subdomains into the correct origin path or proxy target. This is important because subdomain-based tenancy is a core architectural boundary in the system.

11. **Primary request/data flows**
   The main flow is: user authenticates through the API server; creates a project backed by a GitHub URL; triggers a deployment; the API server starts the build worker; the build worker clones/builds/uploads to S3 while streaming logs to Kafka; the log consumer persists logs to TimescaleDB; the proxy/CloudFront layer serves the deployed site by subdomain. The system is therefore split into **control plane**, **build execution**, **log ingestion**, and **traffic serving** concerns.

Main entry points: [`api-server/internal/server/server.go`](https://github.com/sumitk99/cloudrunr/blob/master/api-server/internal/server/server.go) (Server core), [`build-server/script/script.go`](https://github.com/sumitk99/cloudrunr/blob/master/build-server/script/script.go) (Build script), [`api-server/internal/handler/deploy_handler.go`](https://github.com/sumitk99/cloudrunr/blob/master/api-server/internal/handler/deploy_handler.go) (Handlers), [`api-server/internal/repository/repository.go`](https://github.com/sumitk99/cloudrunr/blob/master/api-server/internal/repository/repository.go) (Repositories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["Edge routing"]
  node_cloudfront_function["CloudFront<br/>edge rewrite"]
end

subgraph group_control["Control plane"]
  node_api_main["API entry<br/>go service<br/>[main.go]"]
  node_api_server["Server core<br/>http server<br/>[server.go]"]
  node_api_routes["Routes<br/>routing<br/>[routes.go]"]
  node_api_handlers["Handlers<br/>[deploy_handler.go]"]
  node_api_service["Auth service<br/>business logic<br/>[auth_service.go]"]
  node_api_repo[("Repositories<br/>data access<br/>[repository.go]")]
  node_api_middleware["Middleware<br/>request filters<br/>[auth_middleware.go]"]
  node_api_models["Models<br/>schemas<br/>[models.go]"]
  node_api_kafka["Kafka client<br/>event client<br/>[kafka_server.go]"]
  node_postgres[("PostgreSQL<br/>relational store")]
end

subgraph group_build["Build pipeline"]
  node_build_main["Build entry<br/>worker service<br/>[main.go]"]
  node_build_script["Build script<br/>pipeline logic<br/>[script.go]"]
  node_build_helper["Helpers<br/>[helper.go]"]
  node_s3[("S3 assets<br/>object storage")]
  node_github["GitHub source<br/>git source"]
end

subgraph group_logs["Log pipeline"]
  node_log_consumer["Log consumer<br/>kafka sink<br/>[main.go]"]
  node_timescaledb[("TimescaleDB<br/>log store")]
  node_kafka["Kafka<br/>event bus"]
end

subgraph group_serve["Serving plane"]
  node_proxy_main["Proxy entry<br/>go service<br/>[main.go]"]
  node_proxy_middleware["Proxy middleware<br/>routing middleware<br/>[middleware.go]"]
end

node_cloudfront_function -->|"rewrite to origin"| node_proxy_middleware
node_api_main -->|"start"| node_api_server
node_api_server -->|"register"| node_api_routes
node_api_server -->|"apply"| node_api_middleware
node_api_server -->|"dispatch"| node_api_handlers
node_api_handlers -->|"call"| node_api_service
node_api_handlers -->|"read/write"| node_api_repo
node_api_service -->|"metadata"| node_postgres
node_api_repo -->|"store"| node_postgres
node_api_repo -->|"query logs"| node_timescaledb
node_api_server -->|"events"| node_api_kafka
node_api_handlers -->|"trigger deploy"| node_build_main
node_build_main -->|"orchestrate"| node_build_script
node_build_script -->|"use"| node_build_helper
node_build_script -->|"clone"| node_github
node_build_script -->|"publish"| node_s3
node_build_script -->|"stream logs"| node_kafka
node_log_consumer -->|"consume"| node_kafka
node_log_consumer -->|"persist"| node_timescaledb
node_proxy_middleware -->|"serve assets"| node_s3
node_proxy_middleware -->|"resolve tenant"| node_postgres

click node_cloudfront_function "https://github.com/sumitk99/cloudrunr/blob/master/CloudFrontFunction.js"
click node_api_main "https://github.com/sumitk99/cloudrunr/blob/master/api-server/cmd/api-server/main.go"
click node_api_server "https://github.com/sumitk99/cloudrunr/blob/master/api-server/internal/server/server.go"
click node_api_routes "https://github.com/sumitk99/cloudrunr/blob/master/api-server/internal/routes/routes.go"
click node_api_handlers "https://github.com/sumitk99/cloudrunr/blob/master/api-server/internal/handler/deploy_handler.go"
click node_api_service "https://github.com/sumitk99/cloudrunr/blob/master/api-server/internal/service/auth_service.go"
click node_api_repo "https://github.com/sumitk99/cloudrunr/blob/master/api-server/internal/repository/repository.go"
click node_api_middleware "https://github.com/sumitk99/cloudrunr/blob/master/api-server/internal/middleware/auth_middleware.go"
click node_api_models "https://github.com/sumitk99/cloudrunr/blob/master/api-server/internal/models/models.go"
click node_api_kafka "https://github.com/sumitk99/cloudrunr/blob/master/api-server/internal/server/kafka_server.go"
click node_build_main "https://github.com/sumitk99/cloudrunr/blob/master/build-server/main.go"
click node_build_script "https://github.com/sumitk99/cloudrunr/blob/master/build-server/script/script.go"
click node_build_helper "https://github.com/sumitk99/cloudrunr/blob/master/build-server/helper/helper.go"
click node_log_consumer "https://github.com/sumitk99/cloudrunr/blob/master/log-consumer/main.go"
click node_proxy_main "https://github.com/sumitk99/cloudrunr/blob/master/proxy-server/cmd/proxy-server/main.go"
click node_proxy_middleware "https://github.com/sumitk99/cloudrunr/blob/master/proxy-server/middleware/middleware.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cloudfront_function toneBlue
class node_api_main,node_api_server,node_api_routes,node_api_handlers,node_api_service,node_api_repo,node_api_middleware,node_api_models,node_api_kafka,node_postgres toneAmber
class node_build_main,node_build_script,node_build_helper,node_s3,node_github toneMint
class node_log_consumer,node_timescaledb,node_kafka toneRose
class node_proxy_main,node_proxy_middleware toneIndigo
```

## Components

### Edge routing

CDN and host/path rewriting before traffic reaches the serving layer.

- [CloudFront](https://github.com/sumitk99/cloudrunr/blob/master/CloudFrontFunction.js): edge rewrite · Edge function that normalizes or rewrites requests for routed delivery. · `CloudFrontFunction.js`

### Control plane

API service that manages auth, projects, deployments, and log access.

- [API entry](https://github.com/sumitk99/cloudrunr/blob/master/api-server/cmd/api-server/main.go): go service · Main control-plane process for API requests. · `api-server/cmd/api-server/main.go`
- [Server core](https://github.com/sumitk99/cloudrunr/blob/master/api-server/internal/server/server.go): http server · Wires routes, middleware, handlers, and service dependencies. · `api-server/internal/server/server.go`
- [Routes](https://github.com/sumitk99/cloudrunr/blob/master/api-server/internal/routes/routes.go): routing · API endpoint registration and request surface. · `api-server/internal/routes/routes.go`
- [Handlers](https://github.com/sumitk99/cloudrunr/blob/master/api-server/internal/handler/deploy_handler.go): http handlers · Authentication, deployment, and log request handlers. · `api-server/internal/handler/deploy_handler.go`
- [Auth service](https://github.com/sumitk99/cloudrunr/blob/master/api-server/internal/service/auth_service.go): business logic · Authentication and control-plane business operations. · `api-server/internal/service/auth_service.go`
- [Repositories](https://github.com/sumitk99/cloudrunr/blob/master/api-server/internal/repository/repository.go): data access · Persistence layer for deployments and logs. · `api-server/internal/repository/repository.go`
- [Middleware](https://github.com/sumitk99/cloudrunr/blob/master/api-server/internal/middleware/auth_middleware.go): request filters · JWT auth and request validation before handlers run. · `api-server/internal/middleware/auth_middleware.go`
- [Models](https://github.com/sumitk99/cloudrunr/blob/master/api-server/internal/models/models.go): schemas · Domain structs for users and deployment metadata. · `api-server/internal/models/models.go`
- [Kafka client](https://github.com/sumitk99/cloudrunr/blob/master/api-server/internal/server/kafka_server.go): event client · API-side integration for deployment and log event flow. · `api-server/internal/server/kafka_server.go`
- **PostgreSQL**: relational store · Primary metadata store for users, projects, and deployments.

### Build pipeline

Ephemeral worker that builds and publishes project artifacts.

- [Build entry](https://github.com/sumitk99/cloudrunr/blob/master/build-server/main.go): worker service · Main process for the ephemeral build container. · `build-server/main.go`
- [Build script](https://github.com/sumitk99/cloudrunr/blob/master/build-server/script/script.go): pipeline logic · Orchestrates checkout, install, build, and publish steps. · `build-server/script/script.go`
- [Helpers](https://github.com/sumitk99/cloudrunr/blob/master/build-server/helper/helper.go): runtime helpers · Shared build utilities and environment handling. · `build-server/helper/helper.go`
- **S3 assets**: object storage · Published build output stored per project.
- **GitHub source**: git source · Source repository cloned by the build worker.

### Log pipeline

Streaming log transport and durable log storage.

- [Log consumer](https://github.com/sumitk99/cloudrunr/blob/master/log-consumer/main.go): kafka sink · Consumes build log events and persists them. · `log-consumer/main.go`
- **TimescaleDB**: log store · Time-series storage for persisted deployment logs.
- **Kafka**: event bus · Transport for streaming build and log events.

### Serving plane

Proxy layer that routes requests to deployed project content.

- [Proxy entry](https://github.com/sumitk99/cloudrunr/blob/master/proxy-server/cmd/proxy-server/main.go): go service · Main runtime for request forwarding to deployed apps. · `proxy-server/cmd/proxy-server/main.go`
- [Proxy middleware](https://github.com/sumitk99/cloudrunr/blob/master/proxy-server/middleware/middleware.go): routing middleware · Host or subdomain-based request handling in front of content. · `proxy-server/middleware/middleware.go`

## Connections

- CloudFront → Proxy middleware: rewrite to origin · Edge requests are normalized before they reach the proxy.
- API entry → Server core: start · Entrypoint initializes the API server.
- Server core → Routes: register · Server attaches endpoint routing.
- Server core → Middleware: apply · Authentication and validation are enforced at the boundary.
- Server core → Handlers: dispatch · Requests flow from routes into handlers.
- Handlers → Auth service: call · Handlers delegate business logic to services.
- Handlers → Repositories: read/write · Handlers or services persist and query control data.
- Auth service → PostgreSQL: metadata · Business logic reads and writes relational deployment data.
- Repositories → PostgreSQL: store · Repository layer persists users, projects, and deployments.
- Repositories → TimescaleDB: query logs · Log retrieval uses the time-series store.
- Server core → Kafka client: events · API-side integration coordinates deployment/log event flow.
- Handlers → Build entry: trigger deploy · Deployment requests launch a build worker.
- Build entry → Build script: orchestrate · Worker executes the build pipeline.
- Build script → Helpers: use · Build steps rely on shared helpers.
- Build script → GitHub source: clone · Source is fetched from the project repository.
- Build script → S3 assets: publish · Built assets are uploaded for serving.
- Build script → Kafka: stream logs · Build output is emitted as events.
- Log consumer → Kafka: consume · Consumer reads log events from the bus.
- Log consumer → TimescaleDB: persist · Consumed logs are written to time-series storage.
- Proxy middleware → S3 assets: serve assets · Proxy routes requests toward published project output.
- Proxy middleware → PostgreSQL: resolve tenant · Serving layer may resolve project or subdomain metadata.
