Skip to main content

SkillFlaw deployment architecture

SkillFlaw supports two primary deployment shapes:

  1. Editor deployment: run the backend API together with the frontend UI so teams can build, debug, and operate flows in the product interface.
  2. API-first deployment: run the backend service for programmatic access, and add the frontend and docs only if your environment needs the UI.

On Kubernetes, both shapes are assembled from the same container images and runtime settings used by the project runtime contract. SkillFlaw does not currently ship a first-party Kubernetes Helm chart, so the Kubernetes guides in this section focus on manifest-based deployment using the published GHCR images and the environment variables already used by docker/docker-compose.yml.

Core building blocks​

A typical SkillFlaw deployment is composed of the following services:

  • Backend API: ghcr.io/cwinux/skillflaw_backend:latest
    • serves the REST API on port 7860
    • exposes health checks at /health
    • runs flows through endpoints such as /api/v1/run/{flow_id} and /api/v1/responses
  • Frontend UI: ghcr.io/cwinux/skillflaw_frontend:latest
    • serves the web application
  • Documentation site: ghcr.io/cwinux/skillflaw_docs:latest
    • optional standalone docs service when you want docs on a dedicated host or service
  • PostgreSQL
    • required for persistent application data
  • Redis
    • used when SKILLFLAW_CACHE_TYPE=redis
  • Persistent storage
    • required for SKILLFLAW_CONFIG_DIR and any other runtime-managed state you do not want to lose across pod recreation

Source, container, and Kubernetes delivery​

Source deployment​

Source deployment is the best fit for local development and fast debugging from a source checkout.

  • run make init
  • initialize the database with make init_db
  • run the backend with make backend
  • run the frontend with make frontend
  • build docs locally with make docs or make docs_build

One implementation detail matters here: source deployments serve frontend assets from src/backend/base/skillflaw/frontend, so any source-based UI rollout must rebuild those assets with make build_frontend or a command that includes it, such as make run_cli.

Container deployment​

The project ships a compose-based reference deployment in docker/docker-compose.yml.

That stack brings up:

  • backend
  • frontend
  • doc
  • pgsql
  • redis

Default local access points are:

  • frontend: http://localhost:3001
  • backend health: http://localhost:7860/health
  • docs: http://localhost:3002

Kubernetes deployment​

Kubernetes should mirror the same service boundaries instead of inventing a separate runtime contract:

  • backend pod(s) use the same environment variables as compose
  • frontend pod(s) point BACKEND_URL to the backend service
  • docs should be deployed as a dedicated docs service when the environment needs documentation access
  • PostgreSQL and Redis can be in-cluster for internal environments or external managed services for production

Development and internal test environments​

Deploy the full editor shape when teams need to:

  • design or edit flows in the UI
  • use management pages
  • verify end-to-end interactions through the browser
  • review docs from the same cluster

This environment usually includes backend, frontend, PostgreSQL, Redis, and optionally the standalone docs service.

Production serving environments​

Deploy the API-first shape when the cluster is mainly used to serve already managed flows to applications.

Typical production traffic includes:

  • /api/v1/run/{flow_id_or_alias}
  • /api/v1/responses
  • /api/v1/mcp/streamable

If the environment does not require the web UI, you can expose only the backend and keep the frontend/docs out of the public path.

Routing patterns​

Use explicit service boundaries for public routing:

  • app UI on an application hostname such as app.example.com
  • backend API on an API hostname such as api.example.com
  • docs on a docs hostname such as docs.example.com

The docs site should stay mounted at / on the docs service instead of being attached as a subpath of the frontend application.

Backend-only mode​

For source and CLI-style runs, the backend supports a backend-only mode through the runtime entrypoint and the related environment setting.

Use this when you intentionally want a headless API process, but treat it as a deployment choice rather than a compatibility fallback. In containerized environments, the clearer pattern is usually to deploy only the backend image when you do not need the UI.

What to keep consistent across environments​

Whatever platform you deploy to, keep these contracts stable:

  • the backend listens on port 7860
  • the frontend talks to the backend through BACKEND_URL
  • SKILLFLAW_SECRET_KEY_FILE is mounted as a real file, not hardcoded into an image
  • SKILLFLAW_CONFIG_DIR points to writable persistent storage
  • PostgreSQL and Redis connection settings are explicit and environment-specific

Next steps​