docs: plan backend foundation phase
This commit is contained in:
user
@@ -0,0 +1,93 @@
|
||||
# Phase 1: Go Backend Foundation and Workflow Boundary - Context
|
||||
|
||||
**Gathered:** 2026-04-26
|
||||
**Status:** Ready for planning
|
||||
**Source:** GSD continuation from product planning
|
||||
|
||||
<domain>
|
||||
## Phase Boundary
|
||||
|
||||
Phase 1 establishes the Go backend foundation and the typed workflow boundary.
|
||||
It does not need to implement the full tutoring loop. It should create the
|
||||
minimal service skeleton that future phases can build on without violating the
|
||||
600-line rule, SOLID/KISS/YAGNI, or OpenSpec.
|
||||
|
||||
</domain>
|
||||
|
||||
<decisions>
|
||||
## Implementation Decisions
|
||||
|
||||
### Stack
|
||||
|
||||
- Backend is Go.
|
||||
- The first source package structure should separate app/bootstrap, HTTP
|
||||
transport, config, workflow contracts, and domain placeholders.
|
||||
- The implementation should not introduce a database, queue, UI, auth provider,
|
||||
or image provider in Phase 1 unless needed for scaffold validation.
|
||||
|
||||
### Workflow Boundary
|
||||
|
||||
- `agent-farm-go` patterns are internalized behind typed Go interfaces.
|
||||
- API/handler code must not shell out to workflow scripts directly.
|
||||
- `third-one` / `deepseek-v4-flash` runtime selection belongs behind config and
|
||||
workflow interfaces.
|
||||
- Workflow result contracts should align with
|
||||
`docs/planning/WORKFLOW_CONTRACTS.md`.
|
||||
|
||||
### Engineering Constraints
|
||||
|
||||
- No manually authored source file over 600 lines.
|
||||
- SOLID, KISS, and YAGNI are active constraints.
|
||||
- Keep learner memory, ontology, grading, progression, and assets separated as
|
||||
future module boundaries.
|
||||
|
||||
</decisions>
|
||||
|
||||
<canonical_refs>
|
||||
## Canonical References
|
||||
|
||||
Downstream agents MUST read these before planning or implementing.
|
||||
|
||||
### Product and Requirements
|
||||
|
||||
- `docs/planning/PRD.md` - product direction and MVP scope.
|
||||
- `docs/planning/ARCHITECTURE.md` - Go backend and internalized workflow shape.
|
||||
- `docs/planning/ENGINEERING.md` - implementation constraints.
|
||||
- `.planning/REQUIREMENTS.md` - Phase 1 requirement IDs.
|
||||
- `.planning/ROADMAP.md` - phase goal and success criteria.
|
||||
|
||||
### Workflow Contracts and Specs
|
||||
|
||||
- `docs/planning/WORKFLOW_CONTRACTS.md` - typed workflow contract plan.
|
||||
- `openspec/changes/bootstrap-job-tutor-platform/specs/tutor-workflows/spec.md`
|
||||
- workflow and Go backend requirements.
|
||||
- `openspec/changes/bootstrap-job-tutor-platform/specs/engineering-quality/spec.md`
|
||||
- code-size and design quality requirements.
|
||||
|
||||
</canonical_refs>
|
||||
|
||||
<specifics>
|
||||
## Specific Ideas
|
||||
|
||||
- Start with a small Go module and one health endpoint or CLI smoke path.
|
||||
- Add config structs for runtime/model keys without calling live providers yet.
|
||||
- Add workflow interface definitions and stub implementations that return typed
|
||||
errors or no-op evidence-safe results.
|
||||
- Add tests for config loading and workflow interface behavior where practical.
|
||||
|
||||
</specifics>
|
||||
|
||||
<deferred>
|
||||
## Deferred Ideas
|
||||
|
||||
- Real diagnostic interview flow belongs to Phase 2.
|
||||
- Persistent learner memory belongs to Phase 3.
|
||||
- Progression/readiness map belongs to Phase 4.
|
||||
- Ontology ingestion belongs to Phase 5.
|
||||
- Image asset generation belongs to Phase 6.
|
||||
|
||||
</deferred>
|
||||
|
||||
---
|
||||
*Phase: 001-go-backend-foundation-and-workflow-boundary*
|
||||
*Context gathered: 2026-04-26*
|
||||
@@ -0,0 +1,108 @@
|
||||
# Phase 1 Plan: Go Backend Foundation and Workflow Boundary
|
||||
|
||||
**Status:** Ready for execution
|
||||
**Phase Goal:** Establish the Go service skeleton and typed workflow boundary
|
||||
for internalized `agent-farm-go` patterns.
|
||||
|
||||
## Scope
|
||||
|
||||
This phase creates the backend foundation only. It should not implement the full
|
||||
diagnostic interview loop, persistence, frontend, ontology ingestion, or image
|
||||
generation.
|
||||
|
||||
## Requirements Covered
|
||||
|
||||
- BACK-01: Backend service is implemented in Go.
|
||||
- BACK-02: Backend exposes typed interfaces for tutor workflows.
|
||||
- BACK-03: Backend integrates internalized `agent-farm-go` workflow patterns
|
||||
without ad hoc handler shellouts.
|
||||
- BACK-04: Workflow LLM execution uses `third-one` with configurable runtime and
|
||||
default `deepseek-v4-flash`.
|
||||
- BACK-05: Manually authored source files stay at or below 600 lines.
|
||||
|
||||
## Tasks
|
||||
|
||||
### 1. Initialize Go backend scaffold
|
||||
|
||||
- Create `go.mod`.
|
||||
- Create `cmd/tutor-api/main.go`.
|
||||
- Create minimal app assembly package under `internal/app`.
|
||||
- Keep entrypoint thin and below 600 lines.
|
||||
|
||||
### 2. Add configuration boundary
|
||||
|
||||
- Add `internal/config`.
|
||||
- Support app address, environment name, workflow runtime path, model key, and
|
||||
third-one binary path as config fields.
|
||||
- Default model key to `deepseek-v4-flash`.
|
||||
- Avoid storing secrets in tracked files.
|
||||
|
||||
### 3. Add typed workflow boundary
|
||||
|
||||
- Add `internal/workflows`.
|
||||
- Define minimal Go structs/interfaces for:
|
||||
- `DiagnosticResult`
|
||||
- `GradedAnswer`
|
||||
- `MemoryUpdateCandidate`
|
||||
- `NextChallenge`
|
||||
- `ReadinessUpdate`
|
||||
- Add a narrow runner interface that future internalized `agent-farm-go`
|
||||
execution can satisfy.
|
||||
- Do not call shell commands from HTTP handlers.
|
||||
|
||||
### 4. Add HTTP smoke surface
|
||||
|
||||
- Add `internal/httpapi`.
|
||||
- Add health endpoint such as `GET /healthz`.
|
||||
- Optionally expose config-safe runtime metadata, excluding secrets.
|
||||
|
||||
### 5. Add validation tests
|
||||
|
||||
- Test config defaults.
|
||||
- Test health handler.
|
||||
- Test workflow stub returns typed results or typed not-implemented errors.
|
||||
- Verify no source file exceeds 600 lines.
|
||||
|
||||
### 6. Update repo instructions
|
||||
|
||||
- Add concrete Go build/test commands to `AGENTS.md`.
|
||||
- Update OpenSpec/GSD state if implementation changes scope.
|
||||
|
||||
## Verification
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
go test ./...
|
||||
openspec validate bootstrap-job-tutor-platform --strict
|
||||
```
|
||||
|
||||
Also check manually authored source file length:
|
||||
|
||||
```powershell
|
||||
Get-ChildItem -Recurse -File *.go | ForEach-Object {
|
||||
$lines = (Get-Content -LiteralPath $_.FullName | Measure-Object -Line).Lines
|
||||
if ($lines -gt 600) { throw "$($_.FullName) has $lines lines" }
|
||||
}
|
||||
```
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Database schema.
|
||||
- Authentication.
|
||||
- Real LLM calls.
|
||||
- Live `third-one` execution.
|
||||
- Frontend.
|
||||
- Material ingestion.
|
||||
- Image generation.
|
||||
|
||||
## Plan Quality Check
|
||||
|
||||
- Goal-backward fit: each task supports Go scaffold or typed workflow boundary.
|
||||
- KISS/YAGNI: no database, queue, provider SDK, or full workflow engine in this
|
||||
phase.
|
||||
- SOLID: app, config, HTTP, and workflow responsibilities are separated.
|
||||
- Evidence: build/tests/OpenSpec/file-length checks prove the phase.
|
||||
|
||||
---
|
||||
*Plan created: 2026-04-26*
|
||||
@@ -0,0 +1,69 @@
|
||||
# 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`.
|
||||
Reference in New Issue
Block a user