# overmindv/tasks architecture

> Architecture diagram of the GitHub repository overmindv/tasks, 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/tasks
- Repository: https://github.com/overmindv/tasks

## Overview

`tasks` is an internal service for authoring, publishing, and solving IT tasks. The main workflow is HTTP task retrieval and submission, with choice answers evaluated in-service and programming submissions sent asynchronously to an external sandbox through Kafka; users poll for results. Other documented capabilities include immutable task versions, candidate ingestion and review, problem lists, progress, replay, and result history. The graph preserves these branches. Some subsystem links rely on the README or wiring excerpt because their implementation excerpts were not shown.

Main entry points: [`internal/transport/httpapi/handler.go`](https://github.com/overmindv/tasks/blob/main/internal/transport/httpapi/handler.go) (HTTP routes), [`internal/usecase/code_submissions.go`](https://github.com/overmindv/tasks/blob/main/internal/usecase/code_submissions.go) (Code submissions), [`internal/usecase/candidates.go`](https://github.com/overmindv/tasks/blob/main/internal/usecase/candidates.go) (Candidate review), [`internal/transport/httpapi/candidates.go`](https://github.com/overmindv/tasks/blob/main/internal/transport/httpapi/candidates.go) (Candidate endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_http["HTTP routes<br/>[handler.go]"]
  node_task_api["Task endpoints<br/>[tasks.go]"]
  node_submission_api["Submission endpoints<br/>[submissions.go]"]
  node_code_api["Code endpoints"]
  node_candidate_api["Candidate endpoints<br/>[candidates.go]"]
  node_history_api["History endpoints<br/>[problem_lists.go]"]
end

subgraph group_tasks["Task authoring"]
  node_task_service["Task lifecycle<br/>[tasks.go]"]
  node_task_store[("Task persistence<br/>[tasks.go]")]
end

subgraph group_solving["Submissions and execution"]
  node_choice_service["Choice evaluation<br/>[submissions.go]"]
  node_submission_store[("Submission history<br/>[submissions.go]")]
  node_code_service["Code submissions"]
  node_execution_contract["Execution contract<br/>[contracts.go]"]
  node_execution_store[("Execution queue<br/>[execution_queue.go]")]
  node_outbox["Kafka outbox<br/>[outbox.go]"]
  node_results["Result consumer<br/>[results.go]"]
end

subgraph group_operations["Curation and history"]
  node_candidate_service["Candidate review<br/>[candidates.go]"]
  node_candidate_store[("Candidate queue<br/>[candidates.go]")]
  node_problem_service["Problem lists<br/>[problem_lists.go]"]
  node_progress_service["Progress<br/>[progress.go]"]
  node_replay_service["Execution replay<br/>[replay.go]"]
  node_problem_store[("Problem-list storage<br/>[problem_lists.go]")]
end

node_admin(("Admin"))
node_user(("Task user"))
node_hunter(("task-hunter"))
node_kafka["Kafka"]
node_sandbox["Sandbox"]

node_admin -->|"uses"| node_http
node_user -->|"uses"| node_http
node_hunter -->|"batch ingests"| node_candidate_api
node_http -->|"routes to"| node_task_api
node_http -->|"routes to"| node_submission_api
node_http -->|"routes to"| node_code_api
node_http -->|"routes to"| node_candidate_api
node_http -->|"routes to"| node_history_api
node_task_api -.->|"calls"| node_task_service
node_task_service -->|"persists versions"| node_task_store
node_submission_api -.->|"calls"| node_choice_service
node_choice_service -->|"records answers"| node_submission_store
node_code_api -->|"calls"| node_code_service
node_code_service -->|"queues runs"| node_execution_store
node_code_service -->|"builds requests"| node_execution_contract
node_outbox -->|"claims messages"| node_execution_store
node_outbox -->|"publishes requests"| node_kafka
node_kafka -->|"dispatches runs"| node_sandbox
node_sandbox -->|"publishes results"| node_kafka
node_kafka -->|"delivers results"| node_results
node_results -->|"updates submissions"| node_code_service
node_candidate_api -.->|"calls"| node_candidate_service
node_candidate_service -->|"manages candidates"| node_candidate_store
node_candidate_service -.->|"creates approved tasks"| node_task_service
node_history_api -.->|"calls"| node_problem_service
node_problem_service -->|"reads lists"| node_problem_store
node_admin -.->|"replays runs"| node_replay_service
node_user -.->|"checks progress"| node_progress_service

click node_http "https://github.com/overmindv/tasks/blob/main/internal/transport/httpapi/handler.go"
click node_task_api "https://github.com/overmindv/tasks/blob/main/internal/transport/httpapi/tasks.go"
click node_submission_api "https://github.com/overmindv/tasks/blob/main/internal/transport/httpapi/submissions.go"
click node_code_api "https://github.com/overmindv/tasks/blob/main/internal/transport/httpapi/code_submissions.go"
click node_candidate_api "https://github.com/overmindv/tasks/blob/main/internal/transport/httpapi/candidates.go"
click node_history_api "https://github.com/overmindv/tasks/blob/main/internal/transport/httpapi/problem_lists.go"
click node_task_service "https://github.com/overmindv/tasks/blob/main/internal/usecase/tasks.go"
click node_task_store "https://github.com/overmindv/tasks/blob/main/internal/adapter/postgres/tasks.go"
click node_choice_service "https://github.com/overmindv/tasks/blob/main/internal/usecase/submissions.go"
click node_submission_store "https://github.com/overmindv/tasks/blob/main/internal/adapter/postgres/submissions.go"
click node_code_service "https://github.com/overmindv/tasks/blob/main/internal/usecase/code_submissions.go"
click node_execution_contract "https://github.com/overmindv/tasks/blob/main/internal/execution/contracts.go"
click node_execution_store "https://github.com/overmindv/tasks/blob/main/internal/adapter/postgres/execution_queue.go"
click node_outbox "https://github.com/overmindv/tasks/blob/main/internal/transport/kafka/outbox.go"
click node_results "https://github.com/overmindv/tasks/blob/main/internal/transport/kafka/results.go"
click node_candidate_service "https://github.com/overmindv/tasks/blob/main/internal/usecase/candidates.go"
click node_candidate_store "https://github.com/overmindv/tasks/blob/main/internal/adapter/postgres/candidates.go"
click node_problem_service "https://github.com/overmindv/tasks/blob/main/internal/usecase/problem_lists.go"
click node_progress_service "https://github.com/overmindv/tasks/blob/main/internal/usecase/progress.go"
click node_replay_service "https://github.com/overmindv/tasks/blob/main/internal/usecase/replay.go"
click node_problem_store "https://github.com/overmindv/tasks/blob/main/internal/adapter/postgres/problem_lists.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_http,node_task_api,node_submission_api,node_code_api,node_candidate_api,node_history_api toneBlue
class node_task_service,node_task_store toneAmber
class node_choice_service,node_submission_store,node_code_service,node_execution_contract,node_execution_store,node_outbox,node_results toneMint
class node_candidate_service,node_candidate_store,node_problem_service,node_progress_service,node_replay_service,node_problem_store,node_user,node_hunter toneRose
class node_admin,node_kafka,node_sandbox toneIndigo
```

## Components

### HTTP API

- [HTTP routes](https://github.com/overmindv/tasks/blob/main/internal/transport/httpapi/handler.go): `internal/transport/httpapi/handler.go`
- [Task endpoints](https://github.com/overmindv/tasks/blob/main/internal/transport/httpapi/tasks.go): `internal/transport/httpapi/tasks.go`
- [Submission endpoints](https://github.com/overmindv/tasks/blob/main/internal/transport/httpapi/submissions.go): `internal/transport/httpapi/submissions.go`
- [Code endpoints](https://github.com/overmindv/tasks/blob/main/internal/transport/httpapi/code_submissions.go): `internal/transport/httpapi/code_submissions.go`
- [Candidate endpoints](https://github.com/overmindv/tasks/blob/main/internal/transport/httpapi/candidates.go): `internal/transport/httpapi/candidates.go`
- [History endpoints](https://github.com/overmindv/tasks/blob/main/internal/transport/httpapi/problem_lists.go): `internal/transport/httpapi/problem_lists.go`

### Task authoring

- [Task lifecycle](https://github.com/overmindv/tasks/blob/main/internal/usecase/tasks.go): `internal/usecase/tasks.go`
- [Task persistence](https://github.com/overmindv/tasks/blob/main/internal/adapter/postgres/tasks.go): `internal/adapter/postgres/tasks.go`

### Submissions and execution

- [Choice evaluation](https://github.com/overmindv/tasks/blob/main/internal/usecase/submissions.go): `internal/usecase/submissions.go`
- [Submission history](https://github.com/overmindv/tasks/blob/main/internal/adapter/postgres/submissions.go): `internal/adapter/postgres/submissions.go`
- [Code submissions](https://github.com/overmindv/tasks/blob/main/internal/usecase/code_submissions.go): `internal/usecase/code_submissions.go`
- [Execution contract](https://github.com/overmindv/tasks/blob/main/internal/execution/contracts.go): `internal/execution/contracts.go`
- [Execution queue](https://github.com/overmindv/tasks/blob/main/internal/adapter/postgres/execution_queue.go): `internal/adapter/postgres/execution_queue.go`
- [Kafka outbox](https://github.com/overmindv/tasks/blob/main/internal/transport/kafka/outbox.go): `internal/transport/kafka/outbox.go`
- [Result consumer](https://github.com/overmindv/tasks/blob/main/internal/transport/kafka/results.go): `internal/transport/kafka/results.go`

### Curation and history

- [Candidate review](https://github.com/overmindv/tasks/blob/main/internal/usecase/candidates.go): `internal/usecase/candidates.go`
- [Candidate queue](https://github.com/overmindv/tasks/blob/main/internal/adapter/postgres/candidates.go): `internal/adapter/postgres/candidates.go`
- [Problem lists](https://github.com/overmindv/tasks/blob/main/internal/usecase/problem_lists.go): `internal/usecase/problem_lists.go`
- [Progress](https://github.com/overmindv/tasks/blob/main/internal/usecase/progress.go): `internal/usecase/progress.go`
- [Execution replay](https://github.com/overmindv/tasks/blob/main/internal/usecase/replay.go): `internal/usecase/replay.go`
- [Problem-list storage](https://github.com/overmindv/tasks/blob/main/internal/adapter/postgres/problem_lists.go): `internal/adapter/postgres/problem_lists.go`

### Other components

- **Admin**
- **Task user**
- **task-hunter**
- **Kafka**
- **Sandbox**

## Connections

- Admin → HTTP routes: uses (evidence: `internal/transport/httpapi/handler.go`)
- Task user → HTTP routes: uses (evidence: `internal/transport/httpapi/handler.go`)
- task-hunter → Candidate endpoints: batch ingests
- HTTP routes → Task endpoints: routes to (evidence: `internal/transport/httpapi/handler.go`)
- HTTP routes → Submission endpoints: routes to (evidence: `internal/transport/httpapi/handler.go`)
- HTTP routes → Code endpoints: routes to (evidence: `internal/transport/httpapi/handler.go`)
- HTTP routes → Candidate endpoints: routes to (evidence: `internal/transport/httpapi/handler.go`)
- HTTP routes → History endpoints: routes to (evidence: `internal/transport/httpapi/handler.go`)
- Task endpoints → Task lifecycle: calls
- Task lifecycle → Task persistence: persists versions (evidence: `internal/usecase/tasks.go`)
- Submission endpoints → Choice evaluation: calls
- Choice evaluation → Submission history: records answers (evidence: `internal/usecase/submissions.go`)
- Code endpoints → Code submissions: calls (evidence: `internal/transport/httpapi/code_submissions.go`)
- Code submissions → Execution queue: queues runs (evidence: `internal/usecase/code_submissions.go`)
- Code submissions → Execution contract: builds requests (evidence: `internal/usecase/code_submissions.go`)
- Kafka outbox → Execution queue: claims messages (evidence: `internal/transport/kafka/outbox.go`)
- Kafka outbox → Kafka: publishes requests (evidence: `README.md`)
- Kafka → Sandbox: dispatches runs (evidence: `README.md`)
- Sandbox → Kafka: publishes results (evidence: `README.md`)
- Kafka → Result consumer: delivers results (evidence: `README.md`)
- Result consumer → Code submissions: updates submissions (evidence: `internal/transport/kafka/results.go`)
- Candidate endpoints → Candidate review: calls
- Candidate review → Candidate queue: manages candidates (evidence: `internal/usecase/candidates.go`)
- Candidate review → Task lifecycle: creates approved tasks
- History endpoints → Problem lists: calls
- Problem lists → Problem-list storage: reads lists (evidence: `internal/usecase/problem_lists.go`)
- Admin → Execution replay: replays runs (evidence: `README.md`)
- Task user → Progress: checks progress (evidence: `README.md`)
