# overmindv/recommendations architecture

> Architecture diagram of the GitHub repository overmindv/recommendations, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/overmindv/recommendations
- Repository: https://github.com/overmindv/recommendations

## Overview

This is an internal Go service for previewing practice plans and learning outlines from gateway-supplied topics, tasks, prerequisites, and verified-at-source evidence; it does not fetch those inputs itself. The main workflow authenticates a gateway request, builds a deterministic plan, and may apply bounded AI ranking. Separate APIs manage persisted practice goals and saved learning plans. The README documents the gateway contract and stateless preview; source excerpts show route wiring, planner calls, and PostgreSQL-backed stores. AI-provider internals and some storage wiring are only partly sampled, so those links are omitted or marked unverified.

Main entry points: [`internal/aiplan/engine.go`](https://github.com/overmindv/recommendations/blob/main/internal/aiplan/engine.go) (AI ranking engine), [`cmd/recommendations/main.go`](https://github.com/overmindv/recommendations/blob/main/cmd/recommendations/main.go) (Service bootstrap), [`internal/httpapi/goal_handler.go`](https://github.com/overmindv/recommendations/blob/main/internal/httpapi/goal_handler.go) (Goal API), [`internal/savedplans/postgres.go`](https://github.com/overmindv/recommendations/blob/main/internal/savedplans/postgres.go) (Saved plan PostgreSQL store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_practice_api["Practice API<br/>[handler.go]"]
  node_outline_api["Outline API<br/>[outline.go]"]
  node_goal_api["Goal API<br/>[goal_handler.go]"]
  node_saved_api["Saved plan API<br/>[saved_plans.go]"]
end

subgraph group_planning["Planning"]
  node_ai_engine["AI ranking engine<br/>[engine.go]"]
  node_ai_provider["Ranking provider<br/>[provider.go]"]
  node_planner["Practice planner<br/>[planner.go]"]
  node_planner_insights["Topic insights<br/>[insights.go]"]
  node_outline_engine["Outline generator<br/>[outline.go]"]
end

subgraph group_learning["Learning plans"]
  node_saved_model["Saved plan model<br/>[model.go]"]
end

subgraph group_persistence["Persistence"]
  node_goal_model["Goal model<br/>[goals.go]"]
  node_goal_store["Goal PostgreSQL store<br/>[postgres.go]"]
  node_saved_store["Saved plan PostgreSQL store<br/>[postgres.go]"]
  node_postgres[("PostgreSQL")]
end

subgraph group_runtime["Service runtime"]
  node_service["Service bootstrap<br/>[main.go]"]
  node_config["Configuration<br/>[config.go]"]
end

node_gateway(("Trusted gateway"))

node_gateway -->|"submits inputs"| node_practice_api
node_service -->|"loads settings"| node_config
node_service -->|"registers routes"| node_practice_api
node_service -->|"registers routes"| node_goal_api
node_service -->|"registers routes"| node_saved_api
node_practice_api -->|"builds plan"| node_ai_engine
node_ai_engine -->|"builds candidate plan"| node_planner
node_ai_engine -->|"requests ranking"| node_ai_provider
node_ai_engine -->|"uses plan types"| node_planner
node_outline_api -->|"generates outline"| node_outline_engine
node_outline_engine -.->|"shares cached ranking"| node_ai_engine
node_goal_api -->|"validates goal"| node_goal_model
node_goal_api -->|"reads and writes"| node_goal_store
node_saved_api -->|"manages plans"| node_saved_store
node_saved_store -->|"validates and merges"| node_saved_model
node_goal_store -.->|"persists goals"| node_postgres
node_saved_store -->|"persists plans"| node_postgres
node_planner -.->|"computes insights"| node_planner_insights

click node_service "https://github.com/overmindv/recommendations/blob/main/cmd/recommendations/main.go"
click node_config "https://github.com/overmindv/recommendations/blob/main/internal/config/config.go"
click node_practice_api "https://github.com/overmindv/recommendations/blob/main/internal/httpapi/handler.go"
click node_outline_api "https://github.com/overmindv/recommendations/blob/main/internal/httpapi/outline.go"
click node_goal_api "https://github.com/overmindv/recommendations/blob/main/internal/httpapi/goal_handler.go"
click node_saved_api "https://github.com/overmindv/recommendations/blob/main/internal/httpapi/saved_plans.go"
click node_ai_engine "https://github.com/overmindv/recommendations/blob/main/internal/aiplan/engine.go"
click node_ai_provider "https://github.com/overmindv/recommendations/blob/main/internal/aiplan/provider.go"
click node_planner "https://github.com/overmindv/recommendations/blob/main/internal/planner/planner.go"
click node_planner_insights "https://github.com/overmindv/recommendations/blob/main/internal/planner/insights.go"
click node_outline_engine "https://github.com/overmindv/recommendations/blob/main/internal/aiplan/outline.go"
click node_goal_model "https://github.com/overmindv/recommendations/blob/main/internal/goals/goals.go"
click node_goal_store "https://github.com/overmindv/recommendations/blob/main/internal/goals/postgres.go"
click node_saved_model "https://github.com/overmindv/recommendations/blob/main/internal/savedplans/model.go"
click node_saved_store "https://github.com/overmindv/recommendations/blob/main/internal/savedplans/postgres.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_practice_api,node_outline_api,node_goal_api,node_saved_api toneBlue
class node_ai_engine,node_ai_provider,node_planner,node_planner_insights,node_outline_engine toneAmber
class node_saved_model toneMint
class node_goal_model,node_goal_store,node_saved_store,node_postgres toneRose
class node_service,node_config,node_gateway toneIndigo
```

## Components

### HTTP API

- [Practice API](https://github.com/overmindv/recommendations/blob/main/internal/httpapi/handler.go): `internal/httpapi/handler.go`
- [Outline API](https://github.com/overmindv/recommendations/blob/main/internal/httpapi/outline.go): `internal/httpapi/outline.go`
- [Goal API](https://github.com/overmindv/recommendations/blob/main/internal/httpapi/goal_handler.go): `internal/httpapi/goal_handler.go`
- [Saved plan API](https://github.com/overmindv/recommendations/blob/main/internal/httpapi/saved_plans.go): `internal/httpapi/saved_plans.go`

### Planning

- [AI ranking engine](https://github.com/overmindv/recommendations/blob/main/internal/aiplan/engine.go): `internal/aiplan/engine.go`
- [Ranking provider](https://github.com/overmindv/recommendations/blob/main/internal/aiplan/provider.go): `internal/aiplan/provider.go`
- [Practice planner](https://github.com/overmindv/recommendations/blob/main/internal/planner/planner.go): `internal/planner/planner.go`
- [Topic insights](https://github.com/overmindv/recommendations/blob/main/internal/planner/insights.go): `internal/planner/insights.go`
- [Outline generator](https://github.com/overmindv/recommendations/blob/main/internal/aiplan/outline.go): `internal/aiplan/outline.go`

### Learning plans

- [Saved plan model](https://github.com/overmindv/recommendations/blob/main/internal/savedplans/model.go): `internal/savedplans/model.go`

### Persistence

- [Goal model](https://github.com/overmindv/recommendations/blob/main/internal/goals/goals.go): `internal/goals/goals.go`
- [Goal PostgreSQL store](https://github.com/overmindv/recommendations/blob/main/internal/goals/postgres.go): `internal/goals/postgres.go`
- [Saved plan PostgreSQL store](https://github.com/overmindv/recommendations/blob/main/internal/savedplans/postgres.go): `internal/savedplans/postgres.go`
- **PostgreSQL**

### Service runtime

- [Service bootstrap](https://github.com/overmindv/recommendations/blob/main/cmd/recommendations/main.go): `cmd/recommendations/main.go`
- [Configuration](https://github.com/overmindv/recommendations/blob/main/internal/config/config.go): `internal/config/config.go`

### Other components

- **Trusted gateway**

## Connections

- Trusted gateway → Practice API: submits inputs (evidence: `README.md`)
- Service bootstrap → Configuration: loads settings (evidence: `cmd/recommendations/main.go`)
- Service bootstrap → Practice API: registers routes (evidence: `cmd/recommendations/main.go`)
- Service bootstrap → Goal API: registers routes (evidence: `cmd/recommendations/main.go`)
- Service bootstrap → Saved plan API: registers routes (evidence: `cmd/recommendations/main.go`)
- Practice API → AI ranking engine: builds plan (evidence: `internal/httpapi/handler.go`)
- AI ranking engine → Practice planner: builds candidate plan (evidence: `internal/aiplan/engine.go`)
- AI ranking engine → Ranking provider: requests ranking (evidence: `internal/aiplan/engine.go`)
- AI ranking engine → Practice planner: uses plan types (evidence: `internal/aiplan/engine.go`)
- Outline API → Outline generator: generates outline (evidence: `internal/httpapi/outline.go`)
- Outline generator → AI ranking engine: shares cached ranking
- Goal API → Goal model: validates goal (evidence: `internal/httpapi/goal_handler.go`)
- Goal API → Goal PostgreSQL store: reads and writes (evidence: `internal/httpapi/goal_handler.go`)
- Saved plan API → Saved plan PostgreSQL store: manages plans (evidence: `internal/httpapi/saved_plans.go`)
- Saved plan PostgreSQL store → Saved plan model: validates and merges (evidence: `internal/savedplans/postgres.go`)
- Goal PostgreSQL store → PostgreSQL: persists goals
- Saved plan PostgreSQL store → PostgreSQL: persists plans (evidence: `internal/savedplans/postgres.go`)
- Practice planner → Topic insights: computes insights
