# Kluczowe decyzje projektowe

#sympozium #architektura #design-decisions

## Tabela decyzji

| Decyzja | Prymityw K8s | Uzasadnienie |
|---------|-------------|--------------|
| **Jeden [[Pod]] per agent run** | [[Job]] | Izolacja blast-radius, limity zasobów, automatyczne czyszczenie |
| **Filesystem IPC** | emptyDir volume | Agent pisze do `/ipc/`, [[Sidecar Pattern\|bridge sidecar]] obserwuje via fsnotify i publikuje do [[NATS JetStream]] |
| **[[NATS JetStream]]** | [[StatefulSet]] | Durable pub/sub z replay - kanały i control plane bez bezpośredniego couplingu |
| **[[NetworkPolicy]] isolation** | NetworkPolicy | Agent pods mają deny-all egress; tylko IPC bridge łączy się z event busem |
| **Policy-as-[[CRD - Custom Resource Definition\|CRD]]** | [[Admission Webhook]] | `SympoziumPolicy` gatuje narzędzia i sandboxe - enforcement at admission time |
| **Memory-as-SQLite** | [[PersistentVolumeClaim\|PVC]] + sidecar | SQLite z FTS5 na PVC - semantic search, tagging, upgradeable do vector search |
| **Schedule-as-CRD** | CronJob analogy | `SympoziumSchedule` definiuje recurring tasks z cron expressions |
| **Skills-as-[[ConfigMap i Secret\|ConfigMap]]** | ConfigMap volume | SkillPacks generują ConfigMapy montowane w agent pods |
| **Skill [[Sidecar Pattern\|sidecars]] z auto-[[RBAC]]** | Role/ClusterRole | [[Controller i Reconciler\|Controller]] auto-provisionuje efemeryczny RBAC per run |
| **PersonaPacks** | Operator Bundle | Controller stampuje SympoziumInstances, Schedules i memory ConfigMaps |
| **MCP servers as CRD** | [[Deployment]] + Service | MCPServer CRD zarządza lifecycle, probes tools, bridge translates protocol |
| **Node probe [[DaemonSet]]** | DaemonSet | Odkrywa lokalne inference providers - annotuje nody |

## Analiza filozofii architekturalnej

### Ephemeral over Persistent

Fundamentalna decyzja: **każde wywołanie agenta to nowy pod**. To odwrotność podejścia kagent/CrewAI/LangChain, gdzie agent żyje w długo działającym procesie.

**Zalety:**
- Blast-radius ograniczony do jednego poda
- Natywne skalowanie horyzontalne
- Automatyczne czyszczenie po zakończeniu
- Każdy run ma własny [[SecurityContext]]

**Wady:**
- Cold-start per invocation (mitygowany przez warm pools)
- Brak stanu w pamięci między runami (mitygowany przez persistent memory)

### IPC przez system plików

Agent nie komunikuje się bezpośrednio z control plane. Zamiast tego:

```
Agent → /ipc/*.json → fsnotify watcher → NATS → Controller
```

To podejście:
- Eliminuje zależności sieciowe w kontenerze agenta
- Jest language-agnostic (agent mógłby być w dowolnym języku)
- Pozwala na prostą inspekcję (pliki JSON w woluminie)

### Kubernetes jako framework, nie deployment target

Sympozium nie "deployuje się na Kubernetes" - ono **jest Kubernetes**. Każdy koncept platformy mapuje się 1:1 na prymitywy K8s:

- Agent → [[Job]]/[[Pod]]
- Polityka → [[CRD - Custom Resource Definition|CRD]] + [[Admission Webhook]]
- Skill → [[ConfigMap i Secret|ConfigMap]] + [[Sidecar Pattern|Sidecar]] + ephemeral [[RBAC]]
- Schedule → CronJob-like CRD
- Kanał → [[Deployment]]
- Memory → [[PersistentVolumeClaim|PVC]] + SQLite

---

Powiązane: [[Czym jest Sympozium]] | [[Control Plane]] | [[Model bezpieczeństwa Defence-in-Depth]]