# Architecture

Target architecture:

```text
Kazakhtelecom SIP
  -> Asterisk / PJSIP
  -> inbound dialplan
  -> Stasis(ai-operator)
  -> Go AI Operator
  -> ARI Call Manager
  -> chan_websocket Media Gateway
  -> Voice Provider Adapter
  -> OpenAI Realtime or future provider
  -> Knowledge Base / RAG
```

TZ-01 status:

- Stasis route is not enabled.
- Media gateway is not implemented.
- OpenAI provider is not implemented.
- Knowledge Base / RAG is not implemented.
- Live call handling is disabled.

Created package boundaries:

- `internal/asterisk/ari`: local ARI health-check client.
- `internal/call`: call session, language, and state types.
- `internal/media`: media gateway interfaces and audio chunk types.
- `internal/ai`: voice provider interfaces and events.
- `internal/dialogue`: orchestrator interface and skeleton stub.
- `internal/knowledge`: search repository interface.
- `internal/tools`: future tool names.

## TZ-03 status

The Go service can register ARI app `ai-operator`, read ARI events, parse Stasis and hangup lifecycle events, and manage in-memory sessions. Media Gateway, OpenAI provider, and production route switching are still not implemented.

## TZ-04 status

The service can create ARI externalMedia WebSocket channels, connect to `/media/{connection_id}`, parse media control events, send media control commands, and collect basic media stats. OpenAI and production routing remain disabled.

## TZ-05 status

The service now has a replaceable VoiceProvider layer with a fake provider and OpenAI Realtime skeleton. OpenAI remains behind an adapter. Conversation policy, language/region flow, tools execution, and RAG are not implemented yet.

## TZ-06 Conversation Layer

Call Manager now delegates dialogue state to `internal/dialogue`. The state machine enforces language and region selection before any knowledge-base or business-tool flow. Production routing remains unchanged.

## TZ-07 Language Selection

`internal/dialogue/language` normalizes user text, detects Russian/Kazakh choices, and applies state-aware selection policy. It feeds the Dialogue Orchestrator, which stores strict `ru`/`kk` only.

## TZ-08 Region Resolver Update

TZ-08 adds an offline Kazakhstan Region Resolver with 20 enabled regions, stable `region_code` values, Almaty city/region clarification, false-positive protection, and explicit region-change policy. Production routing remains disabled; OpenAI, PostgreSQL, and Knowledge Base/RAG are still not used at this stage.

## TZ-09 Knowledge Base Update

TZ-09 adds PostgreSQL + pgvector, KGA JSONL ingestion, fake embeddings, hybrid KB search, cross-language fallback for KK queries, citations, and `search_knowledge_base` integration behind the existing language/region guardrail. OpenAI is not called automatically and production routing remains disabled.
## TZ-10 Agent Prompt and Tools

The agent behavior layer sits above Dialogue Orchestrator and below VoiceProvider. It builds the final state-aware prompt, formats KB-grounded answers, preserves no-hallucination behavior, and relays VoiceProvider ToolCall results back through `SendToolResult`.
## TZ-11 Human Handoff / Fallback

The handoff layer sits beside Dialogue Orchestrator. User requests for an operator are detected from transcript text or tool calls, converted into structured handoff requests, policy-gated, and executed by a safe executor. Default mode is `disabled_stub`.


## TZ-12 Audit Layer

The audit layer records call lifecycle, state transitions, redacted transcript events, tool calls, KB searches, handoff/fallback events, provider/media stats, exports and retention dry-runs through `internal/audit`.