Skip to content

Architecture

Kiket’s architecture is designed around configuration-as-code, so every layer respects the repository-first model.

Core Services

  • Application API + real-time UI – Handles authentication, project/issue CRUD, board rendering, and extension management. Boards fetch workflow metadata from cached YAML instead of database tables.
  • Workflow Runtime – Parses KiketScript YAML into executable state machines. Transition events trigger actions, notifications, and webhooks.
  • Sync Workers – SyncWorkflowRepositoryJob pulls .kiket/ directories from GitHub, validates YAML, and persists canonical copies in storage/workflow_sources/. The UI now lets you pick any branch before syncing, so production workflows can track release branches while experiments live on feature branches.
  • Configuration Loader – LoadProjectConfigurationJob runs on the dedicated configuration Sidekiq queue, applying .kiket/project.yaml, team.yaml, permissions, and board manifests after each repository sync. Job telemetry is surfaced in the Workflow Repositories dashboard.
  • Board Configuration Service – Materializes boards from YAML definitions including columns, swimlanes, and automation hints.
  • Extension Gateway – Issues cryptographically signed API keys, processes webhook events, and enforces OAuth scopes when extensions call back into Kiket.

Data Flow

Git Repository (.kiket/*)
        │
        ▼
Sync Worker ──▶ Workflow Cache (storage/workflow_sources/...)
        │                     │
        │                     ├──▶ Workflow Runtime (issue transitions)
        │                     └──▶ Board Configuration Service (UI metadata)
        ▼
Events & Webhooks ──▶ Extensions / Analytics

Repository Precedence

  1. Repository-level .kiket/ directories
  2. Project-level overrides
  3. Organization defaults
  4. Global templates bundled with the app (starter workflows, boards, and issue templates)

This precedence is enforced for workflows, boards, manifests, and future agent definitions. Each sync run records provenance so you can trace UI elements back to Git commits.

Deployment Reference

  • Runtime – Google Cloud Run (containerized web application and background workers)
  • Database – Cloud SQL for PostgreSQL with encrypted secrets
  • Storage – Google Cloud Storage for assets, local disk for workflow cache
  • CI/CD – Cloud Build pipeline builds, tests, migrates, and deploys
  • Monitoring – Cloud Logging, Cloud Monitoring, custom health checks (/up)
  • Health endpoint now verifies Sidekiq workers and alerts if the configuration queue backs up.

Self-hosters can swap services; the only requirement is a POSIX filesystem for storage/workflow_sources/ and background job execution for sync.