70 lines
2.1 KiB
Markdown
70 lines
2.1 KiB
Markdown
|
# 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`.
|