Sam Rolfe
449fdd02c5
- docs/hub-api.md: language decision (Go 1.25) with reason and the frozen v1 routes POST /ask, POST /approve, GET /health, including request/response schemas, bearer-token auth, timeouts, error shapes, logging, versioning, and a safety confirmation that no route is a high-consequence control. - Update README, hub_brief.md open items, and the outline docs so they no longer say the API is undecided or the language is open. Co-Authored-By: Paperclip <noreply@paperclip.ing>
59 lines
1.9 KiB
Markdown
59 lines
1.9 KiB
Markdown
# Central AI Hub — Code Structure Map
|
|
|
|
> **Writing Style**: ASD-STE100 Simplified Technical English (`ste-writing`).
|
|
> **Status**: Planned. The Hub 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
|
|
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 (to build)
|
|
main.go HTTP entry point
|
|
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/`
|