# Central AI Hub — Code Structure Map

> **Writing Style**: ASD-STE100 Simplified Technical English (`ste-writing`).
> **Status**: Skeleton built (AUD-48). Routing (AUD-49) is not built yet.

## Planned Folder Layout

```text
central_ai_llm_master/
  AGENTS.md                 project rules for agents
  hub_brief.md              agreed design (source of truth)
  README.md                 technical readme
  Dockerfile                multi-stage build (static binary, distroless)
  docker-compose.yml        one container, port 8788
  .dockerignore             build context filter
  docs/
    hub-architecture.mmd    Mermaid source
    hub-architecture-map.html  Archify map
    diagrams/               rendered images
    archify/                Archify JSON input
    outline/                AI context documents
    ask-contract.md         Hub to project interface
    hub-api.md              frozen inbound API (v1)
    vikunja-tasks.json      human task list
  src/                      Hub service code
    go.mod                  module hub
    main.go                 HTTP entry point (GET /health)
    hear/                   takes voice or text
    understand/             LLM intent routing
    check/                  authorization and approval
    route/                  dispatch to a destination
    answer/                 reply shaping (text, TTS, notify)
    destinations/           one client per destination
  tests/                    unit and round-trip tests
```

## Entry Points

| Entry point | Use |
|---|---|
| `POST /ask` | Send a voice transcript or text. Returns a reply. |
| `POST /approve` | Admin app confirms a restricted action. |
| `GET /health` | Liveness check. |

The inbound API is frozen. See `docs/hub-api.md`.

## Primary Dependencies

- HTTP server (Go 1.25, standard library `net/http`).
- HTTP client for OmniRoute, Home Assistant, Paperclip.
- MQTT client for voice topics.
- Tavily API client for web search.

## Destinations

Each destination gets one client under `src/destinations/`. The client calls the
destination API. The client does not hold business logic.

## Source Control

- Gitea: `sam/central_ai_llm_master`
- Local: `/home/sam/paseo/projects/central_ai_llm_master/`