# Phase 1 Research

## Question

How should the first Go backend scaffold be shaped so it can internalize
`agent-farm-go` workflow patterns without overbuilding?

## Findings

### Keep the first backend narrow

Phase 1 should prove structure, contracts, and validation, not product behavior.
The safest first slice is:

- `cmd/tutor-api` entrypoint
- internal config package
- internal HTTP/app package
- internal workflow contract package
- small health or version endpoint
- tests for config and workflow boundary behavior

### Prefer typed interfaces over runtime coupling

The backend should expose a `WorkflowRunner` style interface that future phases
can implement using internalized `agent-farm-go` execution. Phase 1 can use
stub/no-op implementations as long as the interface boundaries and contracts are
clear.

### Avoid premature infrastructure

Do not add Postgres, migrations, queues, auth, frontend, or image generation in
Phase 1. Those are real needs later, but adding them before the backend boundary
exists would violate KISS/YAGNI.

### Module boundary recommendation

Initial Go package boundaries:

- `internal/app`: service assembly and dependency wiring
- `internal/config`: environment/runtime config
- `internal/httpapi`: HTTP routing and handlers
- `internal/workflows`: workflow interfaces and typed contracts
- `internal/version`: version/build metadata if needed

Future packages can be added when their phase arrives:

- `internal/interview`
- `internal/learner_memory`
- `internal/progression`
- `internal/ontology`
- `internal/assets`

## Risks

- Making workflow interfaces too generic creates a framework before use.
- Putting typed contracts in HTTP handlers will make future phases hard to
  isolate.
- Shelling out from handlers would contradict the internalized workflow decision.

## Recommendation

Plan Phase 1 as a scaffold and boundary proof:

1. Create Go module and package skeleton.
2. Add config for app address and workflow runtime keys.
3. Add typed workflow contracts from the planning document in minimal Go form.
4. Add a stub workflow runner.
5. Add health endpoint and tests.
6. Document build/test commands in `AGENTS.md`.