# Target Architecture — CyberBrain26 v4.1

**Status:** [NÁVRH] — Based on audit findings and v2.md roadmap  
**Generated:** 2026-10-05  
**Authority:** `.kilo/plans/CyberBrain26cil-031026-v2.md`

---

## Architecture Overview

```
┌─────────────────────────────────────────────────────────────────────┐
│                        Vrstva 0: Uživatel                          │
│  [OVĚŘENO] CLI (Kilo TUI)  ·  [HYPOTÉZA] Web UI (FastAPI+React)   │
│  [HYPOTÉZA] Mobilní (Telegram bot)                                 │
└─────────────────────────────────────────────────────────────────────┘
                             │
┌───────────────────────────▼─────────────────────────────────────────┐
│                  Vrstva 1: Orchestration                           │
│  [OVĚŘENO] Kilo (hlavní orchestrátor)                              │
│    └─→ [OVĚŘENO] OrchestrationBridge (volaný jako nástroj)         │
│         ├─ [OVĚŘENO] PlannerAgent (vlákno plánování)               │
│         ├─ [OVĚŘENO] Dispatcher (výhradně delegátor)               │
│         └─ [OVĚŘENO] AgentRegistry + TaskQueue (duální: in-memory + SQLite)  │
└───────────────────────────┬─────────────────────────────────────────┘
                             │
         ┌───────────────────┼───────────────────┐
         ▼                   ▼                   ▼
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────────┐
│ Vrstva 2a:       │ │ Vrstva 2b:       │ │ Vrstva 2c:           │
│ Security Plane   │ │ Knowledge Plane  │ │ Model Intelligence   │
│                  │ │                  │ │                      │
│ [OVĚŘENO]        │ │ [NÁVRH]          │ │ [ČÁSTEČNĚ OVĚŘENO]   │
│ Identity         │ │ Ingest           │ │ Registry             │
│ Policy           │ │ Extract          │ │ [NÁVRH] Router       │
│ Permission       │ │ Index (FTS5)     │ │ (FreeAuto)           │
│ Approval         │ │ Provenance       │ │ [OVĚŘENO] EgressGate │
│ Audit (HMAC)     │ │ Retrieval        │ │ Health Checker       │
│ [NÁVRH] Firewall │ │ RAG              │ │ Cache                │
│ [OVĚŘENO] EgressGate│ │                │ │                      │
└──────┬───────────┘ └──────┬───────────┘ └────────┬─────────────┘
       │                    │                      │
       ▼                    ▼                      ▼
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────────┐
│ Vrstva 3:        │ │ Vrstva 3:        │ │ Vrstva 3:            │
│ Execution Plane  │ │ Storage          │ │ External Providers   │
│                  │ │                  │ │                      │
│ [OVĚŘENO]        │ │ [OVĚŘENO]        │ │ [NÁVRH] LiteLLM      │
│ Bubblewrap       │ │ SQLite (meta)    │ │ /Ollama              │
│ (Linux proto)    │ │ Originals        │ │ (allowlist only)     │
│ [NÁVRH] cgroup   │ │ (filesystem)     │ │                      │
│ [NÁVRH] PID ns   │ │ FTS5 index       │ │                      │
│ [NÁVRH] nsjail   │ │ Backups          │ │                      │
└──────────────────┘ └──────────────────┘ └──────────────────────┘
```

---

## Module Contracts

### Layer 1: Orchestration

| Component | Interface | Status | Notes |
|-----------|-----------|--------|-------|
| **Kilo Orchestrator** | Main entry point, CLI integration | [OVĚŘENO] | `cli.py` implements all commands |
| **OrchestrationBridge** | Tool interface for Kilo | [OVĚŘENO] | `ptah_bridge.py:PtahBridge` |
| **PlannerAgent** | `execute(task_data) → AgentResult` | [OVĚŘENO] | Max steps validation implemented |
| **Dispatcher** | `_authorize()` → security chain | [OVĚŘENO] | `extension_layer/registry_impl.py` |
| **AgentRegistry** | Register/resolve agents by role | [OVĚŘENO] | In-memory + SQLite persistent |
| **TaskQueue** | Enqueue/dispatch async work | [OVĚŘENO] | Memory + SQLite dual implementation |

### Layer 2a: Security Plane

| Component | Interface | Status | Notes |
|-----------|-----------|--------|-------|
| **Identity** | `AgentIdentity` with scopes/trust | [OVĚŘENO] | `security_plane/identity.py` |
| **Policy** | `PolicyEngine.evaluate()` | [OVĚŘENO] | Role-based action permissions |
| **Permission** | `PermissionGateway.evaluate()` | [OVĚŘENO] | Returns DENY/REQUIRE_APPROVAL/ALLOW |
| **Approval** | `ApprovalManager` (SQLite-backed) | [OVĚŘENO] | Human-in-the-loop approval flow |
| **Audit** | `AuditLog.record()/verify_chain()` | [OVĚŘENO] | Keyless SHA-256 chain, needs HMAC |
| **EgressGate** | `EgressGate.authorize(request)` | [OVĚŘENO] | Provider allowlists, classification |
| **Firewall** | `AIFirewall.inspect()` | [NÁVRH] | Not wired into execution path |

### Layer 2b: Knowledge Plane

| Component | Interface | Status | Notes |
|-----------|-----------|--------|-------|
| **Ingest** | File/PDF/OCR → normalized chunks | [NÁVRH] | F3a prototype |
| **Extract** | Content + metadata extraction | [NÁVRH] | F3a prototype |
| **Index (FTS5)** | SQLite FTS5 full-text search | [NÁVRH] | F3a target |
| **Provenance** | SHA256 + source + timestamp per doc | [NÁVRH] | F3a target |
| **Retrieval** | Query → ranked documents | [HYPOTÉZA] | F3b RAG pipeline |
| **RAG** | Context assembly + generation | [HYPOTÉZA] | F3b-e scope |

### Layer 2c: Model Intelligence

| Component | Interface | Status | Notes |
|-----------|-----------|--------|-------|
| **Registry** | Model metadata + capabilities | [ČÁSTEČNĚ OVĚŘENO] | `model_layer/registry.py` exists |
| **Router (FreeAuto)** | Task → optimal free model | [NÁVRH] | Algorithm TBD, F4 target |
| **EgressGate** | All model calls authorized | [OVĚŘENO] | Integrated in `AuthorizedExecutionService` |
| **Health Checker** | Provider availability monitoring | [HYPOTÉZA] | F4 scope |
| **Cache** | Response caching layer | [HYPOTÉZA] | F4 scope |

### Layer 3: Execution Plane

| Component | Interface | Status | Notes |
|-----------|-----------|--------|-------|
| **Bubblewrap** | `execute(code, lang, timeout)` | [OVĚŘENO] | Linux prototype, not for hostile code |
| **cgroup v2** | Memory/CPU/PID limits | [NÁVRH] | F6 target |
| **PID namespace** | Process isolation | [NÁVRH] | F6 target |
| **nsjail fallback** | Production sandbox | [NÁVRH] | F6 target (ADR-007) |

### Layer 3: Storage

| Component | Interface | Status | Notes |
|-----------|-----------|--------|-------|
| **SQLite (meta)** | Roadmaps, approvals, audit, tasks | [OVĚŘENO] | `data_plane/sqlite_store.py` |
| **Originals** | Source file preservation | [NÁVRH] | F3a scope |
| **FTS5 index** | Full-text search | [NÁVRH] | F3a scope |
| **Backups** | Automated snapshots | [HYPOTÉZA] | F7 scope |

### Layer 3: External Providers

| Component | Interface | Status | Notes |
|-----------|-----------|--------|-------|
| **LiteLLM** | Unified provider proxy | [NÁVRH] | F4 target (ADR-008) |
| **Ollama** | Local model server | [NÁVRH] | F4 fallback |
| **Allowlist** | Provider restriction policy | [OVĚŘENO] | EgressGate enforcement |

---

## Security Sequence (Verified)

```
[OVĚŘENO] identita → scope → policy → approval → egress → execution → audit
```

All gates implemented and tested in current codebase.

---

## Data Flow (Verified)

1. **User** → `cyberbrain plan` → **PlannerAgent** → Roadmap (no action)
2. **User** → `cyberbrain run` → **PtahBridge** → **Dispatcher** → Security chain
3. **Security chain** → Identity check → Scope check → Policy → Approval → Audit
4. **EgressGate** → Provider authorization (if model call)
5. **AuthorizedExecutionService** → Re-verifies → **Bubblewrap** → Execution
6. **Audit** → Records every decision (success/failure/denial)

---

## Open Architectural Questions

| Question | Status | Resolution Target |
|----------|--------|-------------------|
| FreeAuto algorithm design | [HYPOTÉZA] | F4 |
| RAG pipeline stack | [HYPOTÉZA] | F3b |
| Web UI framework | [HYPOTÉZA] | F7+ |
| Mobile channel protocol | [NÁVRH] | F1-R5 |
| Distributed worker protocol | [HYPOTÉZA] | F8+ |

---

## Verification Matrix

| Layer | Test Coverage | Gate Status |
|-------|---------------|-------------|
| Orchestration | 26/26 CLI tests pass | F2 Ready |
| Security Plane | 39/39 tests pass (audit + egress) | F0 Ready |
| Execution Plane | 9/9 Bubblewrap tests pass | F2 Ready |
| Knowledge Plane | 0/0 tests (not implemented) | F3 Planned |
| Model Intelligence | 6/6 Kilo plugin tests pass | F1 Ready |

---

**Next:** ADR definitions (Phase B2) and Decision Matrices (Phase B3)