How sumitk99/cloudrunr works
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: server.go Server core · script.go Build script · deploy_handler.go Handlers · repository.go Repositories
Components 21
Edge routing
CDN and host/path rewriting before traffic reaches the serving layer.
- CloudFront · 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 · Main control-plane process for API requests.
api-server/cmd/api-server/main.go - Server core · Wires routes, middleware, handlers, and service dependencies.
api-server/internal/server/server.go - Routes · API endpoint registration and request surface.
api-server/internal/routes/routes.go - Handlers · Authentication, deployment, and log request handlers.
api-server/internal/handler/deploy_handler.go - Auth service · Authentication and control-plane business operations.
api-server/internal/service/auth_service.go - Repositories · Persistence layer for deployments and logs.
api-server/internal/repository/repository.go - Middleware · JWT auth and request validation before handlers run.
api-server/internal/middleware/auth_middleware.go - Models · Domain structs for users and deployment metadata.
api-server/internal/models/models.go - Kafka client · API-side integration for deployment and log event flow.
api-server/internal/server/kafka_server.go - PostgreSQL · Primary metadata store for users, projects, and deployments.
Build pipeline
Ephemeral worker that builds and publishes project artifacts.
- Build entry · Main process for the ephemeral build container.
build-server/main.go - Build script · Orchestrates checkout, install, build, and publish steps.
build-server/script/script.go - Helpers · Shared build utilities and environment handling.
build-server/helper/helper.go - S3 assets · Published build output stored per project.
- GitHub source · Source repository cloned by the build worker.
Log pipeline
Streaming log transport and durable log storage.
- Log consumer · Consumes build log events and persists them.
log-consumer/main.go - TimescaleDB · Time-series storage for persisted deployment logs.
- Kafka · Transport for streaming build and log events.
Serving plane
Proxy layer that routes requests to deployed project content.
- Proxy entry · Main runtime for request forwarding to deployed apps.
proxy-server/cmd/proxy-server/main.go - Proxy middleware · Host or subdomain-based request handling in front of content.
proxy-server/middleware/middleware.go
Connections 21
- 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.