Core Concepts¶

Understanding Kiket's architecture helps you make the most of the platform. This page covers the mental model you need before diving into workflows and extensions.

The Big Picture¶

Kiket is built around three core ideas:

Configuration as Code — Workflows, boards, and analytics are YAML files in Git
Federated Extensions — Integrations run on your infrastructure, not ours
Compliance by Default — Every action creates an immutable audit record

graph TB
    subgraph "Your Repository"
        A[".kiket/workflows/"]
        B[".kiket/boards/"]
        C[".kiket/analytics/"]
    end

    subgraph "Kiket Platform"
        D[Sync Engine]
        E[Workflow Engine]
        F[Board Engine]
        G[Analytics Engine]
        H[AI Agents]
    end

    subgraph "Your Infrastructure"
        I[Extensions]
        J[Webhooks]
    end

    A --> D
    B --> D
    C --> D
    D --> E
    D --> F
    D --> G
    E --> H
    E --> I
    E --> J
    E --> K[Audit Trail]
    K --> L[Blockchain Anchor]

    style D fill:#7C3AED,stroke:#fff,color:#fff
    style E fill:#7C3AED,stroke:#fff,color:#fff
    style F fill:#7C3AED,stroke:#fff,color:#fff
    style G fill:#7C3AED,stroke:#fff,color:#fff
    style H fill:#7C3AED,stroke:#fff,color:#fff
    style I fill:#F59E0B,stroke:#fff,color:#000
    style J fill:#F59E0B,stroke:#fff,color:#000
    style L fill:#10B981,stroke:#fff,color:#fff

Organizations & Projects¶

Organizations¶

An organization is your top-level container. It represents your company or team and contains:

Users and roles
Projects
Extensions (installed from marketplace or custom-built)
Billing and usage limits
Organization-wide settings

Projects¶

A project is where work happens. Each project has:

Issues (tickets, tasks, bugs, etc.)
Workflows defining how issues move through states
Boards visualizing the workflow
Analytics dashboards
Connected repositories

Organization: Acme Corp
├── Project: Backend API
│   ├── Workflow: development
│   ├── Board: Sprint Board
│   └── Repository: github.com/acme/api
├── Project: Mobile App
│   ├── Workflow: mobile-release
│   ├── Board: Release Board
│   └── Repository: github.com/acme/mobile
└── Project: Support
    ├── Workflow: support-triage
    ├── Board: Support Queue
    └── Repository: github.com/acme/support-workflows

Repositories & Sync¶

The .kiket Directory¶

Kiket reads configuration from the .kiket/ directory in your repository:

your-repo/
└── .kiket/
    ├── workflows/           # State machines and automations
    │   ├── development.yaml
    │   └── support.yaml
    ├── boards/              # Kanban board configurations
    │   └── sprint-board.yaml
    ├── analytics/           # Queries and dashboards
    │   └── team-metrics.yaml
    ├── agents/              # AI agent definitions
    │   └── triage-agent.yaml
    └── extension.yaml       # Optional: if building an extension

Sync Process¶

When you push changes:

Webhook fires — GitHub/GitLab notifies Kiket of the push
Validation — Kiket validates your YAML against schemas
Diff calculation — Changes are compared to current state
Application — Valid changes are applied to the project
Audit log — Every change is recorded with who, what, when

sequenceDiagram
    participant Dev as Developer
    participant Git as GitHub
    participant Kiket as Kiket Platform
    participant Audit as Audit Trail

    Dev->>Git: git push
    Git->>Kiket: Webhook: push event
    Kiket->>Kiket: Fetch .kiket/ files
    Kiket->>Kiket: Validate YAML schemas
    alt Validation passes
        Kiket->>Kiket: Apply configuration
        Kiket->>Audit: Log changes
        Kiket->>Git: Status: success
    else Validation fails
        Kiket->>Git: Status: failed
        Kiket->>Dev: Error notification
    end

Multiple Repositories¶

Projects can attach multiple repositories:

Primary repository — Main workflow and board definitions
Shared repository — Organization-wide templates and reusable components
Extension repository — Custom extension code

Workflows¶

A workflow defines how issues move through your process. Think of it as a state machine with:

States — The stages an issue can be in (backlog, in_progress, review, done)
Transitions — Rules for moving between states
Actions — Automations triggered by state changes
Conditions — Guards that control when transitions are allowed

workflow: development
version: 1

states:
  - backlog
  - in_progress:
      wip_limit: 5
      auto_assign: true
  - review:
      require_approval: 1
  - done:
      on_enter:
        - run: close_issue

transitions:
  - from: backlog
    to: in_progress
    when:
      - field: assignee
        operator: present
  - from: in_progress
    to: review
  - from: review
    to: done
    when: all_approvals_received

Learn more about workflows →

Boards¶

A board is a visual representation of your workflow. Boards are configured in YAML:

board: sprint-board
workflow: development

columns:
  - name: Backlog
    states: [backlog]
  - name: In Progress
    states: [in_progress]
    wip_limit: 5
  - name: Review
    states: [review]
  - name: Done
    states: [done]
    collapsed: true

Boards support:

WIP limits — Visual warnings when columns have too many items
Filters — Show subsets of issues based on criteria
Custom views — Multiple board configurations for the same workflow
Swimlanes — Group issues by assignee, priority, or custom fields

Learn more about boards →

Extensions¶

Extensions are integrations that run on your infrastructure. They receive webhooks from Kiket and can call the Kiket API.

graph LR
    A[Kiket Platform] -->|Signed Webhook| B[Your Extension]
    B -->|API Calls| A
    B --> C[Your Database]
    B --> D[External APIs]

    style A fill:#7C3AED,stroke:#fff,color:#fff
    style B fill:#F59E0B,stroke:#fff,color:#000

Why Federated?¶

No vendor lock-in — Your code runs on your infrastructure
Data sovereignty — Sensitive data never leaves your network
Any language — Build with Python, Node.js, Ruby, Go, Java, .NET, or anything that speaks HTTP
Any hosting — Vercel, AWS Lambda, Google Cloud Run, Kubernetes, bare metal

Extension Lifecycle¶

graph LR
    A[Build] --> B[Test]
    B --> C[Package]
    C --> D[Publish]
    D --> E[Install]
    E --> F[Configure]
    F --> G[Run]

    style A fill:#7C3AED,stroke:#fff,color:#fff
    style D fill:#7C3AED,stroke:#fff,color:#fff
    style G fill:#10B981,stroke:#fff,color:#fff

Learn more about extensions →

Audit Trail & Compliance¶

Every action in Kiket creates an audit record:

Who performed the action
What changed (before/after state)
When it happened
Why (linked to workflow rules or manual action)
Context (issue, project, organization)

Blockchain Anchoring¶

Audit records are batched hourly and anchored to the Polygon blockchain:

Batch collection — Events from the past hour are collected
Merkle tree — Events are hashed into a Merkle tree
Anchor transaction — Root hash is written to Polygon
Verification — Anyone can verify the integrity of any record

This creates tamper-proof evidence that auditors can verify independently—without trusting Kiket.

Learn more about compliance →

AI Agents¶

Kiket includes AI agents that can:

Triage issues — Automatically categorize and prioritize
Route work — Assign to the right person or team
Generate content — Draft responses, summaries, documentation
Analyze patterns — Surface anomalies and insights

AI decisions are explainable—every action includes reasoning traces, confidence scores, and source citations.

agent: triage-bot
model: gemini-1.5-flash

triggers:
  - event: issue.created

actions:
  - analyze_issue
  - suggest_labels
  - recommend_assignee

confidence_threshold: 0.8
require_approval: false

What's Next?¶

Your First Workflow

Build a complete workflow with states, transitions, and automations

First workflow
Build an Extension

Create custom integrations using the SDK

Extension guide
Compliance Deep Dive

Learn about audit trails and certifications

Compliance