Infrastructure Overview
This page provides a conceptual overview of the Shokunin Platform’s cloud infrastructure. It is intended to help contributors understand the deployment topology without requiring access to vendor dashboards or credentials.
For operational procedures, deployment steps, or secret management, refer to terraform/README.md in the repository.
Infrastructure at a Glance
The Shokunin Platform uses two hosting providers:
| Provider | Role |
|---|
| Vercel | Hosts the Next.js frontend (serverless, edge-distributed) |
| GCP (Google Cloud Platform) | Provides data persistence, compute, storage, and AI model access |
Architecture Diagram
The diagram below shows how the major components connect. It is derived from terraform/README.md.
Component Overview
Vercel — Frontend Hosting
The Next.js app (v0-shokunin-ai-platform) is deployed to Vercel. Vercel provides:
- Serverless Next.js runtime (App Router, API routes)
- Global CDN for static assets
- Preview deployments for pull requests
The frontend communicates with GCP services via HTTPS — it never talks to Dolt directly.
GCP Cloud Run — Backend Services
Two backend services run on Cloud Run in a private VPC:
| Service | Description | Port |
|---|
| Beads API | REST API wrapper for the Beads task-tracking system. Bridges HTTPS requests from the frontend/CLI to the Dolt MySQL database. | 8080 |
| Dolt Server | Dolt SQL Server — the persistent data store for Beads. Configured with max-instances=1 (stateful). | 3306 |
GCP Filestore — Persistent Storage for Dolt
Dolt requires persistent storage to survive Cloud Run cold starts. GCP Filestore provides an NFS volume mounted into the Dolt Server container at /var/lib/dolt.
Without Filestore, Dolt data would be lost on container restart.
Firebase / Firestore — Application Data
The platform uses Firebase services for application data:
| Service | Description |
|---|
| Firestore | Primary application database. Stores: projects, workshops, agents, workflow nodes/edges, audit logs, user profiles. |
| Firebase Auth | Authentication provider (planned: will be wired through the shokunin-auth adapter). |
GCP Secret Manager — Secrets
Production secrets (API keys, database passwords) are stored in GCP Secret Manager. The platform services read secrets at runtime. Never store secrets in code or environment files committed to the repo.
GCP Artifact Registry — Container Images
Docker images for the Beads API and Dolt Server are stored in Artifact Registry. CI/CD (GitHub Actions) pushes new images on merge; Cloud Run pulls from this registry.
GCP IAM — Access Control
Service accounts and IAM roles control access between GCP services:
- The platform service account (
shokunin-dev-platform-sa) manages all Terraform-provisioned resources.
- The GitHub Actions service account has Workload Identity Federation configured for CI/CD.
Connectivity Summary
Users
│
▼
Vercel (Next.js app)
│ HTTPS
├──► GCP Cloud Run: Beads API ──MySQL──► Dolt Server ──NFS──► Filestore
│
├──► Firebase (Firestore SDK)
│
└──► Firebase (Auth SDK)
All GCP resources are managed with Terraform. Infrastructure as code lives in terraform/. Key files:
| File | Description |
|---|
terraform/platform/environments/dev/main.tf | Provider config and GCP backend |
terraform/platform/environments/dev/networking.tf | VPC, subnet, VPC connector |
terraform/platform/environments/dev/filestore.tf | NFS persistent storage for Dolt |
terraform/platform/environments/dev/cloud-run-dolt.tf | Dolt SQL Server Cloud Run service |
terraform/platform/environments/dev/cloud-run-beads-api.tf | Beads REST API Cloud Run service |
terraform/platform/environments/dev/artifact-registry.tf | Docker image registry |
terraform/platform/environments/dev/secrets.tf | Secret Manager secrets |
terraform/platform/environments/dev/iam.tf | Service accounts, IAM bindings |
./terraform/scripts/tf plan
./terraform/scripts/tf apply
Terraform applies modify production infrastructure. Always run plan first and review the output before apply. Do not run terraform commands directly — always use the ./terraform/scripts/tf wrapper.
Local vs. Production
| Component | Local Dev | Production |
|---|
| Dolt/Beads backend | Docker Compose (docker-compose.yml) | GCP Cloud Run + Filestore |
| Next.js frontend | bun run dev on localhost:3000 | Vercel (serverless) |
| Firestore | Firebase Emulator (optional) | GCP Firestore |
| Secrets | .env.local | GCP Secret Manager |
This overview is intentionally high-level. For detailed deployment instructions, secret values, or operational runbooks, refer to terraform/README.md and the internal team documentation.
