KAOS/docs/ARCHITECTURE.md

KAOS — Arhitektura

Verzija: 0.3.0 Poslednje azuriranje: 2026-02-21

---

Tech Stack

Komponenta	Tehnologija
Backend	Go 1.22+
HTTP framework	Gin
Frontend	Go templates + HTMX + xterm.js
Terminali	xterm.js 5.5.0 (CDN) + WebSocket
PTY	github.com/creack/pty
WebSocket	github.com/gorilla/websocket
Markdown	github.com/yuin/goldmark
Drag & Drop	Sortable.js
Real-time	Server-Sent Events (SSE)
Baza	Nema (disk je source of truth)

---

Struktura koda

code/
├── cmd/
│   ├── kaos-server/      # HTTP server entry point
│   └── kaos-supervisor/  # CLI supervisor (legacy)
├── internal/
│   ├── config/           # Konfiguracija (env vars)
│   ├── server/           # HTTP handleri, PTY, WS, render
│   └── supervisor/       # Task scanner, file ops
├── web/
│   ├── static/           # CSS, JS (htmx, sortable, theme)
│   └── templates/        # Go templates (go:embed)
│       ├── layout.html
│       ├── console.html
│       └── partials/
│           ├── task-card.html
│           └── task-detail.html
├── go.mod
├── go.sum
└── .env.example

---

Kljucne komponente

Server (server.go)

• Gin router sa svim rutama
• No-cache middleware za dinamicke rute
• SSE event broker za real-time update
• Task session manager za PTY sesije

Task Session Manager (console.go)

• taskSessionManager - mapa PTY sesija po task ID
• startSession() - spawna interaktivni claude u PTY
• Prompt se pise u temp fajl, claude dobija jednolinijsku instrukciju
• Sesije prezivljavaju page reload (PTY na serveru)

PTY Session (pty_session.go)

• consolePTYSession - wrapper oko PTY procesa
• RingBuffer (1MB) za replay output-a
• Subscriber pattern za vise WS klijenata
• spawnTaskPTY() - claude --permission-mode dontAsk

WebSocket Handler (ws.go)

• Konektuje se na postojecu PTY sesiju po kljucu
• Replay buffer na konekciju
• Bidirekcioni: PTY output -> browser, keyboard -> PTY
• Resize podrska

Render Engine (render.go)

• Go templates sa go:embed
• Dashboard, task detail, report modal
• Markdown -> HTML sa goldmark
• Docs sa sidebar layoutom

SSE Events (events.go)

• Event broker sa poll intervalom
• Hash task stanja za detekciju promena
• Broadcast samo kad se nesto promeni

---

Dijagram toka - "Pusti" dugme

Browser: klik "Pusti"
    |
    v
POST /task/T08/run
    |
    v
handleRunTask:
    1. Validacija (status, deps)
    2. MoveTask ready -> active
    3. appendTimestamp
    4. Cita task sadrzaj
    5. buildWorkPrompt -> temp fajl
    6. startSession(T08, "work", ...)
       |
       v
    spawnTaskPTY -> claude --permission-mode dontAsk
       |
       v
    goroutine: ceka first output, salje prompt
    |
    v
    JSON response {status: started, task: T08}
    |
    v
Browser: redirect /console
    |
    v
refreshSessions() -> GET /console/sessions
    |
    v
createTerminal(T08) -> WS /console/ws/T08
    |
    v
Replay buffer + live output

---

Environment varijable

Varijabla	Opis	Primer
KAOS_PORT	HTTP port	8080
KAOS_PROJECT_PATH	Root projekta	/root/projects/KAOS
KAOS_TASKS_DIR	Tasks folder	/root/projects/KAOS/TASKS
KAOS_TIMEOUT	Timeout za agente	300s

---

Testovi

Testovi su razdvojeni po oblasti:

Fajl	Oblast
test_helpers_test.go	Deljeni setup i helper funkcije
api_test.go	REST API endpointi
dashboard_test.go	Dashboard HTML rendering
task_detail_test.go	Task detail, report, run
docs_test.go	Dokumenti stranica
search_test.go	Pretraga
submit_test.go	Prijava taskova
sse_test.go	Server-Sent Events
console_test.go	Konzola, sesije, prompt builderi
ui_test.go	UI ponasanje
timestamp_test.go	Vremena, PTY, RingBuffer
logs_test.go	Server logovi