docs: plan backend foundation phase
This commit is contained in:
user
@@ -58,6 +58,9 @@ Implementation should follow the engineering rules in
|
||||
SOLID responsibility boundaries, KISS implementation choices, and YAGNI for
|
||||
future-only abstractions.
|
||||
|
||||
Initial typed workflow contracts are defined in
|
||||
`docs/planning/WORKFLOW_CONTRACTS.md`.
|
||||
|
||||
Initial workflow set:
|
||||
|
||||
- `diagnose_job_seeker`
|
||||
@@ -91,6 +94,9 @@ Core progression surfaces:
|
||||
- strong-answer portfolio
|
||||
- interview-date campaign plan
|
||||
|
||||
The first progression track is the backend developer interview seed list in
|
||||
`docs/planning/INTERVIEW_TRACKS.md`.
|
||||
|
||||
Progression decisions should read from learner memory and grading evidence.
|
||||
They should be exposed as workflow outputs so the service can explain why a
|
||||
question, reward, or unlock appeared.
|
||||
|
||||
112
docs/planning/INTERVIEW_TRACKS.md
Normal file
112
docs/planning/INTERVIEW_TRACKS.md
Normal file
@@ -0,0 +1,112 @@
|
||||
# Interview Tracks
|
||||
|
||||
## MVP Track: Backend Developer Interview
|
||||
|
||||
The first interview track is backend developer preparation. This track is broad
|
||||
enough to be valuable to job seekers and narrow enough to produce testable
|
||||
diagnostic, grading, memory, and progression behavior.
|
||||
|
||||
## Target User
|
||||
|
||||
- Junior backend developer candidates.
|
||||
- Bootcamp graduates preparing for backend interviews.
|
||||
- Full-stack developers who need backend interview readiness.
|
||||
- Developers changing stack into backend service work.
|
||||
|
||||
## Canonical Concept Seed List
|
||||
|
||||
### 1. HTTP and Web Fundamentals
|
||||
|
||||
- request and response lifecycle
|
||||
- headers, status codes, methods
|
||||
- idempotency and safe methods
|
||||
- cookies, sessions, tokens
|
||||
- latency, timeout, retry basics
|
||||
|
||||
### 2. REST and API Design
|
||||
|
||||
- resource modeling
|
||||
- endpoint shape
|
||||
- validation and error responses
|
||||
- pagination and filtering
|
||||
- versioning
|
||||
- backward compatibility
|
||||
|
||||
### 3. Databases and Indexes
|
||||
|
||||
- relational modeling
|
||||
- primary keys and foreign keys
|
||||
- index purpose and tradeoffs
|
||||
- query plans at a conceptual level
|
||||
- N+1 query problem
|
||||
- migrations
|
||||
|
||||
### 4. Transactions and Consistency
|
||||
|
||||
- ACID
|
||||
- isolation anomalies
|
||||
- transaction boundaries
|
||||
- optimistic vs pessimistic locking
|
||||
- idempotent writes
|
||||
- eventual consistency basics
|
||||
|
||||
### 5. Caching
|
||||
|
||||
- cache-aside
|
||||
- TTL and invalidation
|
||||
- stale data risks
|
||||
- cache stampede
|
||||
- CDN vs application cache
|
||||
- when not to cache
|
||||
|
||||
### 6. Concurrency and Async Work
|
||||
|
||||
- race conditions
|
||||
- locks and coordination
|
||||
- worker queues
|
||||
- retry and dead-letter basics
|
||||
- backpressure
|
||||
- Go goroutine/channel concepts for Go-oriented tracks
|
||||
|
||||
### 7. Testing and Reliability
|
||||
|
||||
- unit vs integration tests
|
||||
- test doubles
|
||||
- contract tests
|
||||
- observability basics
|
||||
- logging and metrics
|
||||
- failure-mode thinking
|
||||
|
||||
### 8. System Design Basics
|
||||
|
||||
- load balancing
|
||||
- horizontal scaling
|
||||
- stateless service design
|
||||
- database bottlenecks
|
||||
- rate limiting
|
||||
- file/object storage
|
||||
- basic architecture tradeoffs
|
||||
|
||||
## Challenge Ladder
|
||||
|
||||
Each concept should support five levels:
|
||||
|
||||
1. Define the concept.
|
||||
2. Explain tradeoffs.
|
||||
3. Debug a realistic scenario.
|
||||
4. Design under constraints.
|
||||
5. Answer under interview pressure.
|
||||
|
||||
## First Boss Question
|
||||
|
||||
"Design a rate-limited backend API for submitting job applications. Cover HTTP
|
||||
API design, database transaction boundaries, duplicate submission prevention,
|
||||
cache behavior, failure handling, and test strategy."
|
||||
|
||||
## MVP Exclusions
|
||||
|
||||
- Advanced distributed systems theory.
|
||||
- Deep database internals.
|
||||
- Language-specific trivia-heavy questions.
|
||||
- Company-specific interview packs.
|
||||
- Frontend, mobile, AI, and DevOps tracks.
|
||||
@@ -85,12 +85,13 @@ The first MVP should prove one loop:
|
||||
7. User sees visible readiness progress, next unlocks, and a recommended next
|
||||
challenge.
|
||||
|
||||
Recommended first track:
|
||||
First track:
|
||||
|
||||
- Backend developer interview preparation.
|
||||
- Topics: HTTP, REST, databases, transactions, caching, concurrency, testing,
|
||||
system design basics, Go or JavaScript/TypeScript depending on first content
|
||||
corpus.
|
||||
- Topics: HTTP and web fundamentals, REST/API design, databases and indexes,
|
||||
transactions and consistency, caching, concurrency/async work, testing and
|
||||
reliability, and system design basics.
|
||||
- Canonical seed list: `docs/planning/INTERVIEW_TRACKS.md`.
|
||||
|
||||
## Core User Flows
|
||||
|
||||
@@ -183,6 +184,8 @@ the configured image generation provider.
|
||||
configuration.
|
||||
- Workflow outputs SHALL prefer typed JSON contracts for grading, memory
|
||||
extraction, ontology updates, and review-plan generation.
|
||||
- Initial workflow contract plan SHALL follow
|
||||
`docs/planning/WORKFLOW_CONTRACTS.md`.
|
||||
|
||||
### Visual teaching assets
|
||||
|
||||
|
||||
200
docs/planning/WORKFLOW_CONTRACTS.md
Normal file
200
docs/planning/WORKFLOW_CONTRACTS.md
Normal file
@@ -0,0 +1,200 @@
|
||||
# Workflow Contracts
|
||||
|
||||
## Purpose
|
||||
|
||||
LLM workflow outputs that affect product state must be typed and inspectable.
|
||||
The Go backend should call internalized workflow interfaces and then persist
|
||||
validated results. Product state must not depend on parsing arbitrary prose.
|
||||
|
||||
These contracts are initial planning contracts. Field names may evolve during
|
||||
implementation, but the responsibilities should remain stable.
|
||||
|
||||
## Shared Types
|
||||
|
||||
```json
|
||||
{
|
||||
"evidence_ref": {
|
||||
"kind": "answer|grading|source|session|asset",
|
||||
"id": "string",
|
||||
"quote": "string",
|
||||
"confidence": 0.0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"concept_ref": {
|
||||
"id": "string",
|
||||
"label": "string",
|
||||
"track": "backend-developer"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## DiagnosticResult
|
||||
|
||||
Produced by `diagnose_job_seeker`.
|
||||
|
||||
```json
|
||||
{
|
||||
"user_id": "string",
|
||||
"track": "backend-developer",
|
||||
"target_role": "junior-backend-developer",
|
||||
"stack": ["go", "postgres"],
|
||||
"initial_readiness": "unknown|fragile|improving|interview_ready|strong_signal",
|
||||
"concept_findings": [
|
||||
{
|
||||
"concept": "concept_ref",
|
||||
"readiness": "unknown|fragile|improving|interview_ready|strong_signal",
|
||||
"reason": "string",
|
||||
"evidence": ["evidence_ref"]
|
||||
}
|
||||
],
|
||||
"recommended_next_concepts": ["concept_ref"]
|
||||
}
|
||||
```
|
||||
|
||||
## GradedAnswer
|
||||
|
||||
Produced by `grade_interview_answer`.
|
||||
|
||||
```json
|
||||
{
|
||||
"answer_id": "string",
|
||||
"question_id": "string",
|
||||
"concepts": ["concept_ref"],
|
||||
"scores": {
|
||||
"correctness": 0,
|
||||
"depth": 0,
|
||||
"communication": 0,
|
||||
"production_judgment": 0
|
||||
},
|
||||
"overall": "miss|partial|solid|strong",
|
||||
"strengths": ["string"],
|
||||
"gaps": ["string"],
|
||||
"misconception_candidates": [
|
||||
{
|
||||
"label": "string",
|
||||
"description": "string",
|
||||
"evidence": ["evidence_ref"],
|
||||
"confidence": 0.0
|
||||
}
|
||||
],
|
||||
"follow_up": {
|
||||
"needed": true,
|
||||
"question": "string",
|
||||
"purpose": "clarify|repair|stretch|pressure_test"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## MemoryUpdateCandidate
|
||||
|
||||
Produced by `extract_learning_memory`.
|
||||
|
||||
```json
|
||||
{
|
||||
"user_id": "string",
|
||||
"source_answer_id": "string",
|
||||
"updates": [
|
||||
{
|
||||
"kind": "concept_mastery|misconception|intervention|review_schedule",
|
||||
"concept": "concept_ref",
|
||||
"proposed_state": "unknown|fragile|improving|interview_ready|strong_signal",
|
||||
"summary": "string",
|
||||
"evidence": ["evidence_ref"],
|
||||
"confidence": 0.0,
|
||||
"durability": "tentative|confirmed"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## NextChallenge
|
||||
|
||||
Produced by `select_next_challenge`.
|
||||
|
||||
```json
|
||||
{
|
||||
"user_id": "string",
|
||||
"track": "backend-developer",
|
||||
"concept": "concept_ref",
|
||||
"ladder_level": "define|tradeoffs|debug|design_constraints|interview_pressure",
|
||||
"question": "string",
|
||||
"rationale": "string",
|
||||
"difficulty_action": "lower|hold|raise|recover",
|
||||
"evidence": ["evidence_ref"]
|
||||
}
|
||||
```
|
||||
|
||||
## ReadinessUpdate
|
||||
|
||||
Produced by `update_readiness_map`.
|
||||
|
||||
```json
|
||||
{
|
||||
"user_id": "string",
|
||||
"track": "backend-developer",
|
||||
"concept_updates": [
|
||||
{
|
||||
"concept": "concept_ref",
|
||||
"previous": "unknown|fragile|improving|interview_ready|strong_signal",
|
||||
"next": "unknown|fragile|improving|interview_ready|strong_signal",
|
||||
"reason": "string",
|
||||
"evidence": ["evidence_ref"]
|
||||
}
|
||||
],
|
||||
"unlocks": [
|
||||
{
|
||||
"kind": "boss_question|review_card|portfolio_entry",
|
||||
"label": "string",
|
||||
"reason": "string"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## OntologyGap
|
||||
|
||||
Produced by `detect_ontology_gaps`.
|
||||
|
||||
```json
|
||||
{
|
||||
"track": "backend-developer",
|
||||
"missing_or_weak": [
|
||||
{
|
||||
"concept": "concept_ref",
|
||||
"gap_type": "missing_prerequisite|weak_evidence|outdated|needs_rubric",
|
||||
"reason": "string",
|
||||
"supporting_sources": ["evidence_ref"],
|
||||
"proposed_action": "generate_candidate|request_source|human_review"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## TeachingAssetPrompt
|
||||
|
||||
Produced by `generate_teaching_asset_prompt`.
|
||||
|
||||
```json
|
||||
{
|
||||
"concept": "concept_ref",
|
||||
"asset_type": "diagram|lesson_slice|worksheet|interview_card",
|
||||
"prompt": "string",
|
||||
"source_evidence": ["evidence_ref"],
|
||||
"model_key": "gpt-image-v2",
|
||||
"requires_model_id_verification": true,
|
||||
"review_state": "candidate"
|
||||
}
|
||||
```
|
||||
|
||||
## Validation Rules
|
||||
|
||||
- Required IDs must be non-empty.
|
||||
- Any state-changing output must include evidence.
|
||||
- Confidence values must be between 0 and 1.
|
||||
- Generated or inferred content starts as `candidate` or `tentative`.
|
||||
- `model_key` is a product config key; production code must verify the actual
|
||||
provider model identifier before image calls.
|
||||
Reference in New Issue
Block a user