Development Guides¶

Comprehensive how-to guides, best practices, and implementation tutorials for developing features in the Dashtam project.

Contents¶

This directory contains step-by-step development guides organized by topic. Each guide provides practical instructions for implementing features, following standards, and contributing to the project.

Directory Structure¶

guides/
├── docker-refactoring-implementation.md
├── docstring-standards.md
├── documentation-implementation-guide.md
├── git-quick-reference.md
├── git-workflow.md
├── index.md
├── jwt-auth-quick-reference.md
├── jwt-authentication-api-guide.md
├── jwt-authentication-database-guide.md
├── jwt-authentication-services-guide.md
├── markdown-linting-guide.md
├── mermaid-diagram-standards.md
├── restful-api-quick-reference.md
├── test-docstring-standards.md
├── testing-best-practices.md
├── testing-guide.md
├── token-rotation.md
└── uv-package-management.md

📄 Documents¶

Git & Version Control¶

• Git Workflow Guide - Complete Git Flow implementation with branching strategy, branch protection, and PR process
• Git Quick Reference - One-page Git commands cheat sheet for common operations

API Development¶

• RESTful API Quick Reference - Quick guide for building REST-compliant APIs
• JWT Auth Quick Reference - JWT authentication patterns and code examples
• Token Rotation - OAuth token rotation detection and refresh implementation

JWT Authentication Implementation¶

Core Implementation Guides:

• JWT Authentication Database Guide - Database schema, tables, and migrations for authentication
• JWT Authentication Services Guide - PasswordService, JWTService, EmailService, AuthService implementation details
• JWT Authentication API Guide - API endpoints, request/response schemas, and authentication flows

Code Quality & Documentation¶

• Docstring Standards - Google-style docstring conventions for Python
• Markdown Linting Guide - Markdown quality standards and fixing linting errors
• Test Docstring Standards - Test documentation conventions
• Mermaid Diagram Standards - Creating diagrams with Mermaid syntax

Project Management & Procedures¶

• UV Package Management - Modern Python package management with UV CLI
• Docker Refactoring Implementation - Multi-environment Docker migration and best practices
• Documentation Implementation Guide - Creating and maintaining documentation
• Testing Best Practices - Testing patterns, fixtures, and conventions
• Testing Guide - Comprehensive testing tutorial with examples

Quick Links¶

Related Documentation:

• Architecture Overview - System design and patterns
• Testing Strategy - Testing approach and framework
• Infrastructure Setup - Docker configuration

External Resources:

• FastAPI Documentation
• SQLModel Documentation
• Pytest Documentation
• Git Documentation

Navigation¶

Parent Directory: ../index.md

Related Directories:

• Architecture - System design and decisions
• Infrastructure - Docker, CI/CD, database
• Testing - Testing documentation

Contributing¶

When adding new guides to this directory:

1. Choose appropriate guide-template.md (located in docs/templates/) - Use for step-by-step how-to guides
2. Include clear prerequisites and requirements
3. Provide complete code examples with explanations
4. Use Mermaid diagrams for visual concepts
5. Document both happy path and error cases
6. Update this index with a link and brief description
7. Run markdown linting: make lint-md-file FILE="path/to/file.md"

Document Information¶

Template: index-section-template.md Created: 2025-10-03 Last Updated: 2025-10-21