Skip to content

MVP Development Documentation

Overview

This folder contains developer-focused documentation for implementing the PopUpSim MVP. These documents complement the main architecture documentation with implementation details, code examples, and development guidelines.

Documentation Structure

Core Documents

  1. MVP Overview - System overview, goals, constraints
  2. Bounded Contexts - 4 MVP contexts and their responsibilities
  3. Domain Model - Domain entities, value objects, services
  4. SimPy Integration - Discrete event simulation integration
  5. Data Flow - Data flow through system
  6. Technology Stack - Detailed technology decisions
  7. File Formats - JSON/CSV format specifications
  8. Testing Strategy - Testing approach and examples
  9. Deployment - Deployment and installation
  10. Migration Path - Path from MVP to full version
  11. Domain Processes - Process flows, state machines, business rules (TEMPLATE)

Main Architecture Documentation

For complete architecture documentation, see: - MVP Architecture - arc42 architecture documentation (12 sections) - Requirements - User stories and requirements

Key Differences

Aspect Architecture Docs Development Docs
Audience Stakeholders, architects Developers, implementers
Focus Decisions, structure, quality Implementation, code, patterns
Format arc42 template Developer guides
Code Examples Conceptual Detailed with type hints
Status Complete Complete

Development Guidelines

Code Standards

  • Python 3.13+ required
  • Type hints mandatory on all functions/methods
  • Pydantic 2.0+ for data validation
  • Ruff for formatting and linting
  • MyPy for type checking
  • Pytest for testing

Project Rules

See .amazonq/rules/project-rules.md in the repository root for complete coding standards.

Quick Start for Developers

  1. Read architecture first: Start with MVP Architecture Overview
  2. Understand contexts: Review Bounded Contexts
  3. Study domain model: Check Domain Model
  4. Review actual code: See popupsim/backend/src/ for implementation
  5. Run tests: Use uv run pytest to verify setup

Documentation Status

Document Status Notes
Core Documents (1-11) ✅ Complete Updated for 4 contexts
Code Examples ✅ Actual implementation Real code from codebase

Implementation Status

Component Status Location
Configuration Context ✅ Implemented contexts/configuration/
Retrofit Workflow Context ✅ Implemented contexts/retrofit_workflow/
Railway Infrastructure Context ✅ Implemented contexts/railway_infrastructure/
External Trains Context ✅ Implemented contexts/external_trains/
SimPy Integration ✅ Implemented shared/infrastructure/simulation/
Resource Management ✅ Implemented contexts/retrofit_workflow/infrastructure/resources/
Event Collection ✅ Implemented contexts/retrofit_workflow/application/event_collector.py
4 Process Coordinators ✅ Implemented contexts/retrofit_workflow/application/coordinators/
Testing ✅ Complete popupsim/backend/tests/ (378 tests, 54% coverage)

Contributing

When updating these development docs: 1. Keep consistent with main architecture 2. Include type hints in all code examples 3. Reference actual implementation files 4. Add cross-references to architecture sections 5. Use English language 6. Follow minimal code principle (no verbose examples)

Questions?