tutor-service/.planning/phases/001-go-backend-foundation-and-workflow-boundary/001-RESEARCH.md

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.