Dashtam Documentation¶

Welcome to the Dashtam financial data aggregation platform documentation. This directory contains comprehensive guides for developers, users, and contributors working with the Dashtam project.

Contents¶

All documentation is organized by audience and purpose to help you quickly find what you need.

Main Sections:

Development Documentation - Architecture, infrastructure, guides, and testing
API Flows - Manual API testing workflows

Directory Structure¶

docs/
├── templates/                     # Documentation templates (START HERE for new docs)
│   ├── api-flow-template.md
│   ├── architecture-template.md
│   ├── audit-template.md
│   ├── general-template.md
│   ├── guide-template.md
│   ├── implementation-template.md
│   ├── index-root-template.md
│   ├── index-section-template.md
│   ├── infrastructure-template.md
│   ├── readme-template.md
│   ├── README.md
│   ├── research-template.md
│   ├── testing-template.md
│   └── troubleshooting-template.md
├── api-flows/                     # Manual API testing workflows
│   ├── auth/
│   │   ├── complete-auth-flow.md
│   │   ├── email-verification.md
│   │   ├── index.md
│   │   ├── login.md
│   │   ├── password-reset.md
│   │   └── registration.md
│   ├── providers/
│   │   ├── index.md
│   │   ├── provider-disconnect.md
│   │   └── provider-onboarding.md
│   └── index.md
├── development/                   # Developer documentation
│   ├── 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
├── research/                      # Research and decision records
│   ├── authentication-approaches-research.md
│   ├── documentation_guide_research.md
│   ├── index.md
│   ├── smoke-test-design-comparison.md
│   └── smoke-test-organization-research.md
├── reviews/                       # Code audits and compliance reviews
│   ├── DOCUMENTATION_AUDIT_2025-10-05.md
│   ├── index.md
│   └── REST_API_AUDIT_REPORT_2025-10-05.md
├── testing/                       # Testing strategy and guides
│   ├── index.md
│   └── strategy.md
└── index.md

Documents¶

Development Documentation¶

Comprehensive guides for developers, including system architecture, development workflows, testing strategies, and infrastructure setup.

Architecture & Design:

Architecture Index - System architecture overview
Overview - High-level system design and components
JWT Authentication - Authentication system design and implementation
RESTful API Design - REST API architecture and compliance
Schemas Design - Request/response schema patterns
Async vs Sync Patterns - Testing strategy decisions
Async Testing Decision - Testing implementation rationale

Infrastructure & Setup:

Infrastructure Index - Infrastructure documentation overview
Docker Setup - Docker configuration and development environment
CI/CD Pipeline - GitHub Actions automation and testing
Database Migrations - Alembic migration management
Environment Flows - Dev, test, and CI environment setup

Developer Guides:

Guides Index - Developer guides overview
Git Workflow - Git Flow branching strategy
Git Quick Reference - Common git commands
Testing Guide - Comprehensive testing tutorial
Testing Best Practices - Testing patterns and strategies
Docstring Standards - Python documentation standards
Test Docstring Standards - Test documentation guidelines
Markdown Linting Guide - Documentation quality standards
Mermaid Diagram Standards - Diagram creation guide
UV Package Management - Modern Python package management
Docker Refactoring Implementation - Docker optimization guide
Documentation Implementation - Doc creation workflow

JWT Authentication Guides:

JWT Auth Quick Reference - Quick authentication reference
JWT Authentication - Services - Service implementation
JWT Authentication - Database - Database schema and models
JWT Authentication - API - API endpoints and flows

Security & Token Management:

Token Rotation - Token refresh and rotation mechanisms
RESTful API Quick Reference - REST pattern reference

Troubleshooting & Issues:

Troubleshooting Index - Troubleshooting guide overview
Async Testing Greenlet Errors - Async test debugging
Test Infrastructure Fixture Errors - Fixture issues
Smoke Test Caplog Solution - Smoke test implementation
Smoke Test CI Debugging - CI test debugging
CI Test Failures TrustedHost - Network middleware issues
Env Directory Docker Mount - Docker mount troubleshooting

Project Planning:

Technical Debt Roadmap - Future improvements and refactoring
Development Index - Complete development documentation index

Testing¶

Testing strategy, guides, and documentation for the test infrastructure.

Testing Index - Testing documentation overview
Testing Strategy - Test pyramid and testing approach

Research & Decisions¶

Technical research, architectural decision records, and comparative analysis of design approaches.

Research Index - Research and decision records navigation
Authentication Approaches Research - Comprehensive comparison of authentication methods
Smoke Test Design Comparison - Smoke test implementation approaches
Smoke Test Organization Research - Test file organization strategies
Documentation Guide Research - Documentation structure research

Code Reviews & Audits¶

Comprehensive code reviews, API audits, and compliance verification.

Reviews Index - Code reviews and audits overview
REST API Audit Report - RESTful API compliance audit
Documentation Audit - Documentation quality audit

API Flows¶

User-centric manual API testing workflows designed for HTTPS-first development environments.

API Flows Index - Navigation for all API testing workflows

Authentication Flows:

Authentication Index - Authentication workflow overview
Registration - User account creation
Email Verification - Email verification workflow
Login - User login process
Password Reset - Password recovery workflow
Complete Auth Flow - Full authentication journey

Provider Flows:

Providers Index - Provider workflow overview
Provider Onboarding - OAuth provider connection
Provider Disconnect - Provider disconnection

Documentation Templates¶

Reusable templates for creating new documentation that follows project standards.

Template system overview and guidelines
Root documentation index template
Section documentation index template
General purpose documentation template
Architecture documentation template
Developer guide template
Infrastructure documentation template
Testing documentation template
Troubleshooting guide template
Research and ADR template
Code audit and review template
API testing workflow template
Implementation guide template
README documentation template

Quick Links¶

Getting Started:

System Architecture - Understand the platform design
Docker Setup - Set up your development environment
Development Index - Browse all development documentation

Essential References:

Testing Strategy - Testing approach and best practices
Git Workflow - Version control guidelines
Documentation template reference

External Resources:

FastAPI Documentation - Web framework reference
SQLModel Documentation - Database ORM reference
Docker Documentation - Container platform reference