3.7 KiB
Engineering Principles
Purpose
This document defines how the tutor platform should be implemented once coding begins. The product is expected to grow across web UI, API backend, workflow orchestration, learner memory, ontology processing, and generated learning assets. Without explicit constraints, those areas can easily collapse into large files and overbuilt abstractions.
Core Rules
0. Backend language
The backend is Go.
This decision aligns the service with agent-farm-go so workflow orchestration
can become an internal product capability rather than a loosely attached
automation script. Keep the Go service modular and avoid turning the backend
into one large workflow coordinator.
1. File size limit
No source file should exceed 600 lines.
When a file approaches the limit, split it by responsibility. Good split points:
- route registration vs handler logic
- handler logic vs service logic
- service orchestration vs domain rules
- domain rules vs persistence adapter
- workflow contract definitions vs workflow execution
- UI page shell vs reusable components
Exemptions:
- generated files
- lockfiles
- vendored files
- external source snapshots
- large fixture data
2. SOLID
Apply SOLID pragmatically:
- Single responsibility: learner memory, ontology, grading, progression, and asset generation should not live in one service.
- Open/closed: add new interview tracks or asset types through data/config and narrow extension points where practical.
- Liskov substitution: adapters should honor shared contracts without hidden behavior changes.
- Interface segregation: avoid giant service interfaces.
- Dependency inversion: domain logic should not depend directly on provider SDKs or database details.
3. KISS
Prefer the simplest implementation that proves the current product loop:
question -> answer -> grading -> memory update -> next challenge
Do not introduce queues, distributed workers, plugin systems, or complex multi-agent orchestration until the MVP loop needs them.
4. YAGNI
Do not build features only because they may be useful later.
Examples to defer until proven necessary:
- multi-school LMS administration
- marketplace course publishing
- company-specific interview packs
- generalized ontology editor
- multiple image providers
- complex economy systems
- social leaderboards
Product Module Boundaries
Initial implementation should keep these responsibilities distinct:
auth: users, sessions, identity providers.interview: questions, rubrics, answers, grading records.learner_memory: profiles, concept mastery, misconceptions, evidence.ontology: concepts, prerequisites, source evidence, generated candidates.progression: readiness maps, challenge ladders, boss questions, streaks.workflows: typed contracts and calls intoagent-farm-go/third-one.assets: generated diagrams, lesson slices, prompt lineage, review state.
The names can change with the chosen stack, but the responsibilities should stay separate.
Workflow Contracts
LLM workflow outputs should be typed and inspectable. Avoid relying on freeform assistant prose for product state changes.
First contracts to define:
DiagnosticResultGradedAnswerMemoryUpdateCandidateNextChallengeReadinessUpdateOntologyGapTeachingAssetPrompt
Review Checklist
Before considering an implementation slice complete:
- No manually authored source file exceeds 600 lines.
- New behavior maps to an OpenSpec requirement or updates OpenSpec.
- The implementation keeps responsibilities separated.
- The simplest useful design was chosen.
- No future-only abstraction was added.
- Tests or smoke checks prove the touched behavior.