System Architecture¶

Comprehensive system design, architectural patterns, and technical decision records for the Dashtam financial data aggregation platform.

Contents¶

This directory contains architectural documentation covering system design, technology decisions, design patterns, and API standards. All documents follow established templates and provide detailed technical context for developers.

Directory Structure¶

architecture/
├── async-testing-decision.md
├── async-vs-sync-patterns.md
├── index.md
├── jwt-authentication.md
├── overview.md
├── restful-api-design.md
└── schemas-design.md

Documents¶

Core Architecture¶

• System Overview - High-level architecture, component relationships, and design philosophy
• Technology stack rationale
• System components and interactions
• Design principles and patterns

Authentication & Security¶

• JWT Authentication - Complete authentication system architecture
• JWT access tokens and opaque refresh tokens design
• Token storage and encryption model
• Complete flow diagrams and security considerations
• Database schema for authentication

API Design¶

• RESTful API Design - RESTful API principles and compliance standards
• REST architectural constraints
• Resource-oriented design patterns
• Consistent HTTP methods and status codes
• API versioning and evolution strategy

• 100% compliance audit and scoring methodology

• Schemas Design - Pydantic schema organization and patterns

• Schema file structure and organization
• Request/response schema patterns
• Database model separation
• Schema reusability and inheritance

Database & Async Patterns¶

• Async vs Sync Patterns - Database access patterns and design tradeoffs
• SQLAlchemy async/await patterns
• Proper query construction with selectinload()
• Connection pooling and session management

• Synchronous testing strategy for async code

• Async Testing Decision - Architectural decision record for synchronous testing

• Comparison of async/sync testing approaches
• Decision rationale and tradeoffs
• Benefits of synchronous testing pattern
• Implementation guidelines

Quick Links¶

Related Documentation:

• Development Guides - How-to guides and implementation details
• Testing Strategy - Testing approach and framework
• Infrastructure Setup - Docker and environment configuration

Implementation Guides:

• JWT Authentication Implementation - Service implementation
• REST API Quick Reference - API patterns cheat sheet

External Resources:

• FastAPI Documentation - Web framework reference
• SQLModel Documentation - ORM and schema patterns
• Pydantic Documentation - Data validation and serialization
• REST API Design Best Practices - REST architectural standards

Navigation¶

Parent Directory: ../index.md

Related Directories:

• Development Guides - Implementation guides and tutorials
• Infrastructure - Docker, CI/CD, database
• Testing - Testing strategy and best practices

Other Documentation:

• README.md (project root) - Project overview
• WARP.md (project root) - Project rules and standards

Contributing¶

When adding new architecture documents to this directory:

1. Choose appropriate architecture-template.md (located in docs/templates/) - Use for system design documents
2. Focus on why decisions were made, not just what was implemented
3. Include diagrams using Mermaid syntax
4. Reference implementation guides for details
5. Document tradeoffs and alternatives considered
6. Update this index with a link and brief description
7. Run markdown linting: make lint-md FILE="path/to/file.md"

Architecture Decision Records (ADRs)¶

When documenting significant architectural decisions:

1. Use the architecture-template.md (located in docs/templates/)
2. Follow the format: Context → Problem → Options → Analysis → Decision → Consequences
3. Document decision date and decision maker
4. Include links to related implementations
5. Update WARP.md (project root) if the decision impacts project standards

Document Information¶

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