tutor-service/docs/planning/ENGINEERING.md

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 into agent-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:

• DiagnosticResult
• GradedAnswer
• MemoryUpdateCandidate
• NextChallenge
• ReadinessUpdate
• OntologyGap
• TeachingAssetPrompt

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.