Files

Sam Rolfe 449fdd02c5 Freeze Hub inbound API v1; choose Go for the service

- 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>

2026-10-10 17:07:07 +11:00

1.9 KiB

Raw Blame History

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

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/

1.9 KiB Raw Blame History