AI/Developer Teaching Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
The AI/Developer Teaching Guidelines for the MoodTune Backend project establish a mandatory protocol for implementing new features and maintaining the codebase. This system ensures that all development tasks—regardless of size—are documented, explained, and structured to facilitate self-learning for developers while maintaining high architectural standards across the FastAPI-based service.
The guidelines enforce a strict separation between documentation and implementation. Instead of immediate code generation, the process requires the creation of teaching documents that explain the "why" and "how" of a task, followed by a specific prompt that allows the developer to execute the implementation themselves.
Sources: CLAUDE.md:67-76
Feature Implementation Workflow
The project follows a specific order of operations when adding new endpoints or features. Developers and AI agents must adhere to this sequence to ensure consistency across Pydantic schemas, business logic, and API registration.
Standard Implementation Sequence
- Schema: Define request and response Pydantic models in
app/schemas/<feature>.py. - Service: Implement business logic in
app/services/<feature>_service.py. - Router: Define routes in
app/api/v1/<feature>.pyand call the corresponding service. - Register: Include the new router in the main
api_routerwithinapp/api/v1/api.py. - Test: Create comprehensive pytest suites in the
tests/directory.
Sources: CLAUDE.md:41-47
Teaching Rule Protocol
When tasked with a backend feature, the following steps are mandatory:
- Document Creation: A new file must be created in
docs/with the naming conventionYYYYMMDD_<feature-slug>.md. - Task Explanation: The document must detail the task's purpose, the files impacted, and the architectural rationale.
- Implementation Prompt: A ready-to-use prompt must be included at the bottom of the document.
- Stop Execution: The AI must not write the implementation code directly; it must stop after delivering the guide and prompt.
Sources: CLAUDE.md:67-76
Architectural Patterns and Standards
The MoodTune backend relies on specific patterns for asynchronous operations, authentication, and error handling that must be taught to new contributors.
Core Development Patterns
| Pattern | Requirement | Source |
|---|---|---|
| Concurrency | All route handlers and services must use async def. | CLAUDE.md:60 |
| Authentication | Protected routes must use the Depends(get_current_user) dependency. | CLAUDE.md:49-56 |
| Models | Pydantic v2 BaseModel with ConfigDict(from_attributes=True) is required. | CLAUDE.md:62-65 |
| Data Access | Use Supabase Python client directly; SQLAlchemy is prohibited. | CLAUDE.md:8-10 |
Technical Feature Flow
The following diagram illustrates the data flow for an audio analysis request, which is a core component of the system.
The system utilizes temporary file storage for audio processing before cleaning up resources to ensure efficient memory usage.
Sources: app/services/audio_analysis_service.py:31-104, app/api/v1/song_analysis.py:126-155
Testing and Quality Guidelines
Testing is a critical part of the teaching process, as defined in the project's comprehensive test plan. Developers are expected to verify features through both automated pytest suites and manual verification.
Testing Commands
- All Tests:
pytest tests/ -v - Specific Module:
pytest tests/test_analysis.py -v - Local Execution:
uvicorn app.main:app --reload
Sources: CLAUDE.md:17-23
Verification Sequence
The sequence diagram below outlines the verification process for Spotify integration, a frequent point of failure in development.
Sources: TEST_PLAN.md:105-188
Configuration and Environment Management
Teaching guidelines include proper setup of the environment to avoid configuration drift between development, staging, and production.
| Variable | Description | Default/Sample |
|---|---|---|
ENVIRONMENT | Target deployment environment | development |
MAX_UPLOAD_SIZE_MB | Maximum audio file size limit | 15 |
TEMP_AUDIO_DIR | Directory for temporary librosa processing | /tmp/moodtune-audio |
ALLOWED_AUDIO_FORMATS | List of supported file extensions | mp3, m4a, flac, wav, ogg |
Sources: app/core/config.py:65-90
Conclusion
The AI/Developer Teaching Guidelines serve as the backbone of the MoodTune Backend's maintainability. By requiring structured documentation and explicit implementation prompts, the project ensures that every contributor understands the underlying logic of the valence-energy mood model, the Supabase data layer, and the strict asynchronous requirements of the FastAPI framework. Reiteration of these patterns in the docs/ directory prevents technical debt and facilitates rapid, standardized onboarding for new backend features.