oxspeak_server/.junie/plans/migrate-dtos-to-domain.md

sessionId

sessionId
session-260729-161736-1psq

Requirements

Overview & Goals

Migrate all DTOs (Data Transfer Objects) currently located in src/routes/<module>/dto.rs into the src/domain/ directory. This aligns the project architecture by separating domain types and DTOs from HTTP routing and handler implementation details.

Scope

• In Scope:
  • Moving all DTO files from src/routes/<module>/dto.rs to src/domain/<module>/dto.rs (or equivalent domain submodules).
  • Updating all imports across the codebase (src/routes/..., handlers, mappers, etc.) to reference the new domain locations.
  • Re-exporting or organizing modules cleanly in src/domain/mod.rs.
• Out of Scope:
  • Modifying business logic or changing DTO field definitions.
  • Changing database models (src/models/).

Functional Requirements

• Every DTO previously defined in src/routes/*/dto.rs must be accessible under src/domain/.
• All handlers, mappers, and services must compile successfully after updating their imports.
• OpenAPI schema generation via utoipa must continue to function correctly with the relocated DTOs.

Technical Design

Current Implementation

Currently, each feature module in src/routes/<module>/ contains a dto.rs file (along with handlers.rs, mapper.rs, routes.rs, service.rs, domain.rs). Meanwhile, src/domain/ currently only contains events/ and mod.rs.

Key Decisions

• Domain DTO Folder Organization: Centralize all DTOs into a dedicated src/domain/dto/ folder (e.g., src/domain/dto/auth.rs, src/domain/dto/user.rs, etc., declared in src/domain/dto/mod.rs and re-exported or accessed via crate::domain::dto::<module>::*).
• Import Path Updates: Update all use crate::routes::<module>::dto::* imports to use crate::domain::dto::<module>::* (or via crate::domain::dto::*).

Proposed Changes

1. Create a src/domain/dto/ directory with individual module files (e.g., auth.rs, user.rs, etc.) and a src/domain/dto/mod.rs.
2. Move the contents of src/routes/<module>/dto.rs to src/domain/dto/<module>.rs.
3. Update src/domain/mod.rs to declare pub mod dto; and configure src/domain/dto/mod.rs.
4. Update all files referencing src/routes/<module>::dto to point to src/domain::dto::<module> (or crate::domain::dto::<module>).
5. Remove dto.rs from each src/routes/<module>/ directory and update src/routes/<module>/mod.rs.

File Structure Changes

• Added:
  • src/domain/dto/mod.rs
  • src/domain/dto/auth.rs (and other DTO files like user, channel, message, category, role, attachment, core, etc.)
• Modified:
  • src/domain/mod.rs
  • src/routes/<module>/mod.rs for each migrated module (removing pub mod dto;)
  • All handler, mapper, and route files importing the old DTO paths.
• Removed:
  • src/routes/<module>/dto.rs for all modules.

Testing

Validation Approach

• Run cargo check to verify that all type references and module paths compile correctly.
• Run cargo test to ensure tests pass and there are no runtime regressions.
• Inspect OpenAPI generation / documentation endpoints to ensure utoipa correctly registers all DTO schemas.

Delivery Steps

Step 1: Create domain DTO directory and module structure

• Create src/domain/dto/ directory along with src/domain/dto/mod.rs.
• Set up module declarations for each DTO file (auth, user, channel, message, category, role, attachment, core, etc.) under src/domain/dto/.
• Expose pub mod dto; in src/domain/mod.rs.

Step 2: Migrate DTO files to src/domain/dto/ and update imports

• Move each dto.rs file from src/routes/<module>/dto.rs into src/domain/dto/<module>.rs.
• Update all import statements across handlers, mappers, services, and route files in src/routes/ and elsewhere to reference crate::domain::dto::<module>::*.
• Remove the old dto.rs files from src/routes/<module>/ and remove pub mod dto; from src/routes/<module>/mod.rs.

Step 3: Verify compilation and test suite

• Run cargo check and cargo test to ensure all DTO types resolve correctly and there are no broken imports or compilation errors.\n- Verify OpenAPI schema generation (utoipa) correctly picks up the migrated DTO schemas.