# 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 |