Skip to content

PLAN.md

Latest commit

 

History

History
94 lines (56 loc) · 3.35 KB

PLAN.md

File metadata and controls

94 lines (56 loc) · 3.35 KB
Raw

PLAN.md — Task Resolver

Goal

HTTP service that accepts a job (list of shell tasks with optional requires dependencies), sorts them into a valid execution order, and returns either sorted JSON or a bash script.

Greenfield project in this repository.

Scope

In scope: topological sort, input validation (Ecto), JSON + bash output, OpenAPI spec(would be a plus), Docker-compose local setup, tests.

Out of scope: executing shell commands, persistence, auth, job queues.

Architecture (high level)

flowchart LR
    Client -->|POST /api/sort| Router
    Router --> Validation
    Validation --> Sorter
    Sorter -->|sorted tasks| JSON
    Sorter -->|sorted tasks| Bash
Loading

Implementation details (algorithm choice, error shapes, endpoint naming, etc.) go in DECISIONS.md as each phase is completed.

Phases

Phase 1 — Project setup

  • mix new . --app task_resolver
  • Dependencies: bandit, plug, ecto (changeset validation only), jason, credo
  • Supervision tree starting Bandit on port 4000
  • Create empty DECISIONS.md

Phase 2 — Core logic & Validation

  • Contract Validation: Ecto embedded schema for task input (name, command, optional requires).
  • Graph & Sorting: Model tasks as a dependency graph (DAG) and implement topological sort in lib/task_resolver/core/sorter.ex.
  • Error Handling: Detect schema errors, cycles, duplicate names, and broken dependencies; return {:error, reason} tuples.
  • Tests: Unit & contract tests for valid payloads, challenge example, cycles, unknown deps, and edge cases.
  • Entry point: TaskResolver.resolve_tasks/1 glues JobValidator → Sorter into a single call for the future HTTP layer.

Phase 3 — HTTP layer

  • POST /resolve via Plug router (see DECISIONS.md for the endpoint naming choice).
  • Content negotiation via Accept header:
    • application/json (or */*) → sorted tasks JSON
    • text/plain or text/x-shellscript → bash script with shebang.
  • Handle error mapping (map core {:error, reason} to appropriate HTTP status codes: 400, 406, 415, 422).
  • OpenAPI specification (docs/openapi.yaml).
  • Integration tests: 200 vs error codes, both output formats.

Phase 4 — Infrastructure & Delivery

  • Local-oriented Dockerfile & docker-compose.yml for quick running.
  • README.md — local setup, Docker-compose setup, curl examples.
  • Complete DECISIONS.md — design choices and trade-offs.
  • mix format + mix credo --strict.

Expected deliverables

Artifact Purpose
Working repo Runnable app with tests
README.md Setup and run instructions (local + Docker)
DECISIONS.md Design choices and trade-offs, updated incrementally
PLAN.md This high-level roadmap

Definition of done

  • Challenge example returns correct order in JSON and bash
  • Invalid inputs (schema errors, cycles, bad codes) return correct error statuses
  • mix test passes
  • App runs locally (mix run --no-halt) and via docker-compose up
  • OpenAPI spec is available/generated
  • README and DECISIONS.md are complete