Development¶

Comprehensive developer documentation for the Dashtam financial data aggregation platform. This directory contains architecture guides, development workflows, testing strategies, and infrastructure documentation.

Contents¶

This directory contains 39 documents across 4 main subdirectories plus technical debt planning, organized by topic and use case. Each subdirectory has its own index for navigation and quick access.

Directory Structure¶

development/
├── architecture/
│   ├── async-testing-decision.md
│   ├── async-vs-sync-patterns.md
│   ├── index.md
│   ├── jwt-authentication.md
│   ├── overview.md
│   ├── restful-api-design.md
│   └── schemas-design.md
├── 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
├── infrastructure/
│   ├── ci-cd.md
│   ├── database-migrations.md
│   ├── docker-setup.md
│   ├── environment-flows.md
│   └── index.md
├── troubleshooting/
│   ├── async-testing-greenlet-errors.md
│   ├── ci-test-failures-trustedhost.md
│   ├── env-directory-docker-mount-issue.md
│   ├── index.md
│   ├── smoke-test-caplog-solution.md
│   ├── smoke-test-ci-debugging-journey.md
│   └── test-infrastructure-fixture-errors.md
├── technical-debt-roadmap.md
└── index.md

Documents¶

Architecture¶

System design, patterns, and technical decisions:

• Architecture Index - Navigation for all architecture documents
• System Overview - High-level architecture and design philosophy
• RESTful API Design - Complete REST architecture with compliance standards
• JWT Authentication - Authentication system architecture and security model
• Schemas Design - Pydantic schema organization and patterns
• Async vs Sync Patterns - Database access patterns and testing strategies
• Async Testing Decision - Architectural decision record for synchronous testing

Guides¶

Step-by-step how-to documentation for developers:

• Guides Index - Navigation for all development guides

Git and Version Control:

• Git Workflow Guide - Complete Git Flow workflow with branching strategy
• Git Quick Reference - One-page cheat sheet for common Git operations

API Development:

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

JWT Authentication Implementation:

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

Code Quality & Testing:

• Docstring Standards - Google-style docstring conventions
• Test Docstring Standards - Test documentation conventions
• Testing Best Practices - Testing patterns and conventions
• Testing Guide - Comprehensive testing tutorial with examples
• Markdown Linting Guide - Markdown quality standards and fixing errors
• Mermaid Diagram Standards - Diagram creation guidelines

Project Management:

• UV Package Management - Modern Python package management with UV
• Docker Refactoring Implementation - Multi-environment Docker migration
• Documentation Implementation Guide - Creating and maintaining documentation

Infrastructure¶

Docker, environments, database, and CI/CD:

• Infrastructure Index - Navigation for all infrastructure documents
• Docker Multi-Environment Setup - Comprehensive Docker architecture guide
• Environment Flows - Development, test, and CI/CD environment workflows
• Database Migrations - Alembic migration system and best practices
• CI/CD Pipeline - GitHub Actions configuration and automation

Troubleshooting¶

Problem diagnosis and solutions for common issues:

• Troubleshooting Index - Navigation for troubleshooting docs
• Async Testing Greenlet Errors - Fixing async/sync testing conflicts
• CI Test Failures TrustedHost - Resolving CI middleware issues
• Env Directory Docker Mount Issue - Docker volume configuration problems
• Test Infrastructure Fixture Errors - Pytest fixture issues
• Smoke Test Caplog Solution - Smoke test implementation guide
• Smoke Test CI Debugging Journey - CI test debugging walkthrough

Project Planning¶

• Technical Debt Roadmap - Technical debt tracking and development planning

Quick Links¶

Getting Started:

• System Overview - Understand the architecture
• Docker Setup - Set up your environment
• Git Workflow - Understand version control

Essential References:

• RESTful API Quick Reference - REST API patterns
• JWT Auth Quick Reference - Authentication patterns
• Git Quick Reference - Git commands cheat sheet

External Resources:

• FastAPI Documentation
• Docker Compose Documentation
• pytest Documentation
• SQLModel Documentation

Navigation¶

Parent Directory: ../index.md

Related Sections:

• API Flows - Manual API testing workflows
• Research - Technical research and ADRs
• Testing - Testing strategy and documentation

Other Documentation:

• Main Index - Documentation home
• README.md (project root) - Project overview

Contributing¶

When adding new documents to the development directory:

1. Choose appropriate based on document type
2. Place in correct subdirectory (architecture, guides, infrastructure, troubleshooting)
3. Follow markdown quality standards and guidelines
4. Update this index with link and brief description
5. Run markdown linting: make lint-md FILE="path/to/file.md"

Document Information¶

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