Memory 019eaef6

Memory ID (Session ID): 019eaef6-56cc-7000-9b4c-92412d2da8c2
Last Updated: 2026-06-10 03:04:20

Fact Summary

Project: StoryMatrix

1. Critical Architecture Pitfall (DI Container): container.py is a massive ~1300-line God Object. Do NOT attempt to split it into subsets (e.g., DatabaseContainer, AudioContainer). Splitting carries an 8-12 hour regression risk. Maintain the monolith for DI setup. Experimental stubs in infrastructure/containers/ are deprecated/purged.
2. Identity & UUIDs: Deterministic UUID generation (uuid5) must be centralized via domain utilities in src/[[projects/storymatrix|StoryMatrix]]/domain/utils/identity.py (e.g., generate_character_id). Do not duplicate this logic across services like story_creation_service.py or crew_transformer_service.py.
3. Path Handling: Use pathlib.Path properties (.suffix, .stem) instead of primitive string manipulations like .rsplit() (e.g., in src/[[projects/storymatrix|StoryMatrix]]/utils/path_utils.py) for multi-platform robustness.
4. Observability/Tracing: Ensure central domain/application services (e.g., StoryOrchestrationService and its core methods like execute_story_generation_pipeline, generate_story_plan_and_data, generate_timeline) are decorated with OpenTelemetry’s @tracer.start_as_current_span to avoid tracing gaps between CrewAI and domain logic.
5. Imports: Hoist imports to module level. Avoid deeply nested/inline imports (e.g., json, CharacterDTO) within functions to prevent performance hits and PEP-8 violations.
6. Testing: CLI tests can be verified using the command: APP__DEV_LOCAL_ONLY=true uv run pytest tests/unit/test_cli.py.
7. Subagent Tooling: To dispatch subagents (e.g., for reviews), use the task tool with agent: "reviewer" and a tasks array defining the id, description, and assignment payload.

Reference Session

• Associated Chat Session: 019eaef6-56cc-7000-9b4c-92412d2da8c2