asepharyana-hub-scraper/docs/superpowers/specs/2026-05-08-clean-architecture-design.md

Design Spec: Clean-Modular Architecture Refactor

Date: 2026-05-08
Topic: Refactor apps/rust from Hybrid to Clean-Modular Architecture.

1. Purpose

Standardize codebase structure for rigidity, maintainability, and clear separation of concerns (SOC) without violating the Zero-Bloat Policy.

2. Target Architecture

Moving from current structure to a three-tier modular design:

A. Presentation Layer (src/presentation/)

• API Handlers: Pure Axum handlers.
• DTOs: Request/Response models for external communication.
• Middleware: Cross-cutting concerns (CORS, Metrics, Logging).

B. Core Layer (src/core/) - The Domain

• Models: Pure data structures (Plain Rust Objects).
• Repository Traits: Abstract interfaces for data persistence.
• Use Cases: Orchestration of business logic (e.g., ScrapeAnime, ProcessImage).
• Dependencies: None (or minimal shared utils).

C. Infrastructure Layer (src/infra/) - The Adapters

• Repositories: SeaORM & Redis implementations of Core traits.
• Scrapers: Site-specific parsing logic implementing Core scraping traits.
• External Clients: HTTP Client (reqwest), Browser Pool.

D. Shared Layer (src/shared/)

• Utils: Low-level helpers (Date, JSON, String).
• Config: Application configuration.
• Errors: Centralized error handling.

3. Implementation Strategy

1. Phase 1: Scaffold new directory structure.
2. Phase 2: Migrate models and entities to core/models and infra/repositories.
3. Phase 3: Refactor scraping logic into infra/scrapers and define traits in core.
4. Phase 4: Move Axum handlers to presentation/api and update routing.
5. Phase 5: Cleanup helpers into shared/utils.

4. Constraints

• Zero-Bloat: No new heavy dependencies for the sake of abstraction.
• Performance: Maintain latency metrics as defined in docs/development.md.
• SeaORM: Entities stay in infra/ to keep core/ pure.

5. Success Criteria

• All tests pass.
• /metrics show no latency regression.
• Circular dependencies are eliminated.
• Folder structure matches this spec.