typetype-architecture

TypeType Architecture

Overview

TypeType = PySide6/QML typing practice app. Clean Architecture + Ports & Adapters.

Dependency direction (MUST follow):

QML UI → Presentation → Application → Domain/Ports → Integration/Infrastructure

Directory Structure

src/backend/
├── application/
│   ├── exception_handler.py  # Global exception → user message mapping
│   ├── gateways/
│   │   ├── score_gateway.py      # DTO conversion + clipboard
│   │   └── text_source_gateway.py # Text source routing + Port adapter
│   └── usecases/
│       └── load_text_usecase.py # Text loading orchestration
├── ports/             # Protocol definitions (top-level)
│   ├── async_executor.py
│   ├── auth_provider.py
│   ├── char_stats_repository.py
│   ├── clipboard.py
│   ├── local_text_loader.py
│   ├── ranking_repository.py
│   └── text_provider.py
├── config/
│   └── runtime_config.py  # Text sources configuration
├── domain/
│   └── services/        # Pure business logic (NO Qt dependency)
│       ├── typing_service.py
│       ├── auth_service.py
│       └── char_stats_service.py
├── models/             # Data models
│   ├── entity/          # Domain entities (char_stat, session_stat)
│   └── dto/             # Data transfer objects
├── infrastructure/      # Infrastructure
│   ├── api_client.py    # HTTP client wrapper
│   └── network_errors.py # Network error classification
├── integration/         # Port implementations
├── presentation/
│   ├── bridge.py       # QML facade (appBridge)
│   └── adapters/       # Qt adaptation layer
├── security/           # Encryption + secure storage
├── utils/              # Logger
└── workers/            # Background tasks (QRunnable)

Layering Rules (MUST Follow)

✅ ALLOWED Dependencies

Bridge → Adapters
Adapters → Application (UseCases/Gateways)
Adapters → Domain (pure business calls directly)
Application → Domain / Ports / Config
Integration / Infrastructure → Ports / Domain

❌ FORBIDDEN Dependencies