Kun
GitHub
Switch language to العربية

Architecture

PreviousNext

System design, topology, and security architecture for Kun

Architecture

System Design

Kun follows a centralized architecture where all developers connect to a shared infrastructure, ensuring consistent AI context and pattern compliance.

End-to-end Development Flow
Developer
Tailscale VPN
Tailscale VPN
Remote Server
Remote Server
tmux Session
tmux Session
Claude Code
Claude Code
Generated Code

Network Topology

Phase 1: Individual Setup

┌─────────────────────────────────────────────────────────────┐
│                    Developer's Devices                       │
│                                                              │
│   ┌─────────┐    ┌─────────┐    ┌─────────┐                │
│   │ Laptop  │    │ Phone   │    │ Tablet  │                │
│   └────┬────┘    └────┬────┘    └────┬────┘                │
│        │              │              │                       │
│        └──────────────┼──────────────┘                       │
│                       │                                       │
│                       ▼                                       │
│              ┌───────────────┐                               │
│              │   Tailscale   │  ← WireGuard-based VPN       │
│              │    Network    │                               │
│              └───────┬───────┘                               │
│                      │                                       │
│                      ▼                                       │
│              ┌───────────────┐                               │
│              │  Home Server  │                               │
│              │  ├── tmux     │  ← Persistent sessions       │
│              │  └── Claude   │  ← AI development            │
│              └───────────────┘                               │
└─────────────────────────────────────────────────────────────┘

Phase 2: Team Server

Phase 2: Team Server
Ubuntu Server
Multi-user accounts
Create Users
Create Users
Access control
Tailscale ACLs
Tailscale ACLs
/etc/claude-code/
Shared Config
Shared Config
Auto-start
Systemd Services
Systemd Services
Health checks
Netdata

Security Model

Defense in Depth

LayerTechnologyPurpose
NetworkTailscale VPNZero-trust network access
AuthTailscale SSHCertificate-based authentication
AccessACLsRole-based access control
Secrets1Password/VaultCentralized secret management
AuditSystemd journalActivity logging

Access Control

{
  "acls": [
    {
      "action": "accept",
      "src": ["group:developers"],
      "dst": ["tag:dev-server:22"]
    },
    {
      "action": "accept",
      "src": ["group:admins"],
      "dst": ["*:*"]
    }
  ]
}

Directory Structure

kun/— Remote AI Development Infrastructure
scripts/— Setup and maintenance scripts
phase1/— Individual developer setup
phase2/— Team server setup
phase3/— Commercial platform setup
monitoring/— Health check scripts
config/— Configuration templates
tailscale/— Tailscale ACL configs
tmux/— tmux session configs
docker/— Container configurations
Dockerfile— Development container
docker-compose.yml— Multi-container setup
docs/— Project documentation
PROJECT-BRIEF.md— Vision and goals
ARCHITECTURE.md— System design
PRD.md— Requirements
EPICS.md— User stories
src/— Next.js documentation site
app/— App Router pages
components/— React components

Technology Stack

ComponentTechnology
OSUbuntu 22.04/24.04 LTS
VPNTailscale
Sessionstmux
AIClaude Code CLI
RuntimeNode.js 20.x
Package Managerpnpm
Secrets1Password CLI / Vault
MonitoringNetdata

Architecture Principles

1. Mirror-Pattern

Every URL route maps 1:1 to directory structure.

2. Architecture-First

Design systems, not just features. AI generates code within intentional constraints.

3. Guardrails

CLAUDE.md files and patterns are training data for AI collaborators.

4. Human Review Layer

Humans own architectural tradeoffs; AI handles implementation velocity.

Integration with Pattern Library

From databayt/codebase:

  • 54 UI components
  • 62 Atom components
  • 31 Templates
  • 11 Claude agents
  • 4 Claude commands