# dmertins/video-catalog-admin architecture

> Architecture diagram of the GitHub repository dmertins/video-catalog-admin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dmertins/video-catalog-admin
- Repository: https://github.com/dmertins/video-catalog-admin

## Overview

1. **Repository shape**
   - This is a **multi-module Gradle** project with three architectural modules: **domain**, **application**, and **infrastructure**.
   - `buildSrc` holds shared Gradle convention logic, so build setup is centralized rather than duplicated per module.
   - The repo targets **JDK 17**.

2. **Overall architectural direction**
   - The intended design is **DDD + Clean Architecture**.
   - The **domain** module is the core model layer.
   - The **application** module is the orchestration/use-case layer.
   - The **infrastructure** module is the outer layer for technical integrations and adapters.
   - The README states that layers only know the layers above them, which means the core domain abstractions are meant to remain independent of infrastructure concerns.

3. **Domain as the system core**
   - The `domain` module contains the reusable building blocks for modeling the business:
     - `Aggregate`
     - `Entity`
     - `Identifier`
     - `ValueObject`
   - These types establish the DDD vocabulary used by concrete models and keep identity, equality, and aggregate boundaries consistent.

4. **Concrete bounded context currently present**
   - The only concrete subdomain visible in the tree is **Category** under `domain/category`.
   - README also names **Video**, **Cast Member**, and **Genre**, but those are not yet present in the file tree, so the repository is currently only partially implemented.

5. **Category model boundary**
   - `Category` is the main aggregate/entity in the current codebase slice.
   - `CategoryID` is the identity type for that model.
   - `CategorySearchQuery` represents query criteria for retrieving categories.
   - `CategoryGateway` is a domain-facing port, likely the abstraction for persistence or retrieval operations.
   - `CategoryValidator` concentrates business rule checks for the category entity.

6. **Validation subsystem**
   - The domain includes a small validation framework:
     - `Validator`
     - `ValidationHandler`
     - `Error`
     - `ThrowsValidationHandler`
   - This indicates validation is handled inside the domain rather than delegated to infrastructure or UI layers.
   - The presence of a throwing handler suggests validation errors can be accumulated and then converted into domain exceptions.

7. **Exception strategy**
   - `DomainException` and `NoStackTraceException` define the domain’s error model.
   - This signals that business-rule failures are treated as first-class domain outcomes, not generic runtime errors.
   - `NoStackTraceException` suggests an optimization or a deliberate choice to reduce noise for expected domain failures.

8. **Cross-cutting domain utility**
   - `Pagination` exists in the domain module, so paged retrieval is treated as part of the domain contract rather than an infrastructure detail.
   - That matters for the architecture diagram because category search is not just a repository concern; it is a modeled use case shape.

9. **Application layer role**
   - The `application` module exists, but no source files are shown in the tree.
   - Based on the architecture description, this layer is intended to hold **use cases, orchestration, and transaction boundaries** that consume domain objects and domain gateways.
   - It likely mediates between input/output models and the domain core, but its implementation is not visible here.

10. **Infrastructure layer role**
   - The `infrastructure` module also exists without visible source files.
   - In this architecture, it is the place for concrete adapters: persistence, external services, configuration, and execution/runtime wiring.
   - Its role is to implement domain/application ports such as `CategoryGateway`.

11. **Testing footprint**
   - There is a domain unit test for `Category` under `domain/src/test/...`.
   - That suggests the domain is intended to be verified independently from technical adapters, which fits the Clean Architecture boundary.

12. **What the diagram should emphasize**
   - Show a **core domain module** with generic DDD primitives and a **Category bounded context**.
   - Show **CategoryGateway** as the main abstraction crossing from domain to outer layers.
   - Show **Application** as the use-case orchestrator between inbound requests and domain logic.
   - Show **Infrastructure** as the adapter layer implementing technical concerns and gateway implementations.
   - The current repo content is strongest in the domain layer; application/infrastructure are architectural placeholders in the tree rather than fully populated subsystems.

Main entry points: [`domain/build.gradle`](https://github.com/dmertins/video-catalog-admin/blob/main/domain/build.gradle) (Domain Module), [`domain/src/main/java/com/dmertins/videocatalogadmin/domain/category/Category.java`](https://github.com/dmertins/video-catalog-admin/blob/main/domain/src/main/java/com/dmertins/videocatalogadmin/domain/category/Category.java) (Category), [`application/build.gradle`](https://github.com/dmertins/video-catalog-admin/blob/main/application/build.gradle) (Use Cases), [`buildSrc/src/main/groovy/video.catalog.admin.java-conventions.gradle`](https://github.com/dmertins/video-catalog-admin/blob/main/buildSrc/src/main/groovy/video.catalog.admin.java-conventions.gradle) (Conventions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build"]
  node_buildsrc_conventions["Conventions<br/>gradle"]
end

subgraph group_domain["Domain"]
  node_domain_module["Domain Module<br/>[build.gradle]"]
  node_domain_core["DDD Primitives<br/>domain primitives<br/>[Aggregate.java]"]
  node_domain_validation["Validation Core<br/>[Validator.java]"]
  node_domain_error["Domain Errors<br/>exception model"]
  node_domain_pagination["Pagination<br/>domain contract<br/>[Pagination.java]"]
  node_category_aggregate["Category<br/>aggregate<br/>[Category.java]"]
  node_category_id(("Category ID<br/>identifier<br/>[CategoryID.java]"))
  node_category_query["Category Query<br/>query model"]
  node_category_port["Category Gateway<br/>port"]
  node_category_rules["Category Rules<br/>validator"]
  node_validation_handler["Throwing Handler<br/>validation handler"]
end

subgraph group_application["Application"]
  node_application_module["Application Module<br/>[build.gradle]"]
  node_application_usecases["Use Cases<br/>orchestration<br/>[build.gradle]"]
end

subgraph group_infrastructure["Infrastructure"]
  node_infrastructure_module["Infrastructure Module<br/>[build.gradle]"]
  node_infrastructure_adapters["Adapters<br/>adapter layer<br/>[build.gradle]"]
end

node_buildsrc_conventions -->|"configures"| node_domain_module
node_buildsrc_conventions -->|"configures"| node_application_module
node_buildsrc_conventions -->|"configures"| node_infrastructure_module
node_domain_module -->|"contains"| node_domain_core
node_domain_module -->|"contains"| node_domain_validation
node_domain_module -->|"contains"| node_domain_error
node_domain_module -->|"contains"| node_domain_pagination
node_domain_core -->|"supports"| node_category_aggregate
node_domain_core -->|"supports"| node_category_id
node_category_aggregate -->|"validated by"| node_category_rules
node_category_aggregate -->|"searched with"| node_category_query
node_category_aggregate -->|"exposes"| node_category_port
node_category_rules -->|"reports to"| node_validation_handler
node_application_module -->|"contains"| node_application_usecases
node_application_usecases -->|"uses"| node_category_port
node_application_usecases -->|"orchestrates"| node_category_aggregate
node_infrastructure_module -->|"contains"| node_infrastructure_adapters
node_infrastructure_adapters -->|"implements"| node_category_port
node_infrastructure_adapters -->|"supports"| node_application_usecases

click node_buildsrc_conventions "https://github.com/dmertins/video-catalog-admin/blob/main/buildSrc/src/main/groovy/video.catalog.admin.java-conventions.gradle"
click node_domain_module "https://github.com/dmertins/video-catalog-admin/blob/main/domain/build.gradle"
click node_domain_core "https://github.com/dmertins/video-catalog-admin/blob/main/domain/src/main/java/com/dmertins/videocatalogadmin/domain/Aggregate.java"
click node_domain_validation "https://github.com/dmertins/video-catalog-admin/blob/main/domain/src/main/java/com/dmertins/videocatalogadmin/domain/validation/Validator.java"
click node_domain_error "https://github.com/dmertins/video-catalog-admin/blob/main/domain/src/main/java/com/dmertins/videocatalogadmin/domain/exceptions/DomainException.java"
click node_domain_pagination "https://github.com/dmertins/video-catalog-admin/blob/main/domain/src/main/java/com/dmertins/videocatalogadmin/domain/pagination/Pagination.java"
click node_category_aggregate "https://github.com/dmertins/video-catalog-admin/blob/main/domain/src/main/java/com/dmertins/videocatalogadmin/domain/category/Category.java"
click node_category_id "https://github.com/dmertins/video-catalog-admin/blob/main/domain/src/main/java/com/dmertins/videocatalogadmin/domain/category/CategoryID.java"
click node_category_query "https://github.com/dmertins/video-catalog-admin/blob/main/domain/src/main/java/com/dmertins/videocatalogadmin/domain/category/CategorySearchQuery.java"
click node_category_port "https://github.com/dmertins/video-catalog-admin/blob/main/domain/src/main/java/com/dmertins/videocatalogadmin/domain/category/CategoryGateway.java"
click node_category_rules "https://github.com/dmertins/video-catalog-admin/blob/main/domain/src/main/java/com/dmertins/videocatalogadmin/domain/category/CategoryValidator.java"
click node_validation_handler "https://github.com/dmertins/video-catalog-admin/blob/main/domain/src/main/java/com/dmertins/videocatalogadmin/domain/validation/handler/ThrowsValidationHandler.java"
click node_application_module "https://github.com/dmertins/video-catalog-admin/blob/main/application/build.gradle"
click node_application_usecases "https://github.com/dmertins/video-catalog-admin/blob/main/application/build.gradle"
click node_infrastructure_module "https://github.com/dmertins/video-catalog-admin/blob/main/infrastructure/build.gradle"
click node_infrastructure_adapters "https://github.com/dmertins/video-catalog-admin/blob/main/infrastructure/build.gradle"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_buildsrc_conventions toneBlue
class node_domain_module,node_domain_core,node_domain_validation,node_domain_error,node_domain_pagination,node_category_aggregate,node_category_id,node_category_query,node_category_port,node_category_rules,node_validation_handler toneAmber
class node_application_module,node_application_usecases toneMint
class node_infrastructure_module,node_infrastructure_adapters toneRose
```

## Components

### Build

Shared Gradle setup and project conventions

- [Conventions](https://github.com/dmertins/video-catalog-admin/blob/main/buildSrc/src/main/groovy/video.catalog.admin.java-conventions.gradle): gradle · Shared Java convention plugin · `buildSrc/src/main/groovy/video.catalog.admin.java-conventions.gradle`

### Domain

Core DDD model and business rules

- [Domain Module](https://github.com/dmertins/video-catalog-admin/blob/main/domain/build.gradle): module · Core domain dependency boundary · `domain/build.gradle`
- [DDD Primitives](https://github.com/dmertins/video-catalog-admin/blob/main/domain/src/main/java/com/dmertins/videocatalogadmin/domain/Aggregate.java): domain primitives · Aggregate, Entity, Identifier, ValueObject · `domain/src/main/java/com/dmertins/videocatalogadmin/domain/Aggregate.java`
- [Validation Core](https://github.com/dmertins/video-catalog-admin/blob/main/domain/src/main/java/com/dmertins/videocatalogadmin/domain/validation/Validator.java): validation · Validator and validation handler contracts · `domain/src/main/java/com/dmertins/videocatalogadmin/domain/validation/Validator.java`
- [Domain Errors](https://github.com/dmertins/video-catalog-admin/blob/main/domain/src/main/java/com/dmertins/videocatalogadmin/domain/exceptions/DomainException.java): exception model · DomainException and no-stack-trace failures · `domain/src/main/java/com/dmertins/videocatalogadmin/domain/exceptions/DomainException.java`
- [Pagination](https://github.com/dmertins/video-catalog-admin/blob/main/domain/src/main/java/com/dmertins/videocatalogadmin/domain/pagination/Pagination.java): domain contract · Paged query/result shape · `domain/src/main/java/com/dmertins/videocatalogadmin/domain/pagination/Pagination.java`
- [Category](https://github.com/dmertins/video-catalog-admin/blob/main/domain/src/main/java/com/dmertins/videocatalogadmin/domain/category/Category.java): aggregate · Current bounded-context root · `domain/src/main/java/com/dmertins/videocatalogadmin/domain/category/Category.java`
- [Category ID](https://github.com/dmertins/video-catalog-admin/blob/main/domain/src/main/java/com/dmertins/videocatalogadmin/domain/category/CategoryID.java): identifier · Identity type for category · `domain/src/main/java/com/dmertins/videocatalogadmin/domain/category/CategoryID.java`
- [Category Query](https://github.com/dmertins/video-catalog-admin/blob/main/domain/src/main/java/com/dmertins/videocatalogadmin/domain/category/CategorySearchQuery.java): query model · Search criteria for category retrieval · `domain/src/main/java/com/dmertins/videocatalogadmin/domain/category/CategorySearchQuery.java`
- [Category Gateway](https://github.com/dmertins/video-catalog-admin/blob/main/domain/src/main/java/com/dmertins/videocatalogadmin/domain/category/CategoryGateway.java): port · Domain-facing retrieval/persistence abstraction · `domain/src/main/java/com/dmertins/videocatalogadmin/domain/category/CategoryGateway.java`
- [Category Rules](https://github.com/dmertins/video-catalog-admin/blob/main/domain/src/main/java/com/dmertins/videocatalogadmin/domain/category/CategoryValidator.java): validator · Business rule validation for category · `domain/src/main/java/com/dmertins/videocatalogadmin/domain/category/CategoryValidator.java`
- [Throwing Handler](https://github.com/dmertins/video-catalog-admin/blob/main/domain/src/main/java/com/dmertins/videocatalogadmin/domain/validation/handler/ThrowsValidationHandler.java): validation handler · Converts validation problems into failures · `domain/src/main/java/com/dmertins/videocatalogadmin/domain/validation/handler/ThrowsValidationHandler.java`

### Application

Use-case orchestration layer

- [Application Module](https://github.com/dmertins/video-catalog-admin/blob/main/application/build.gradle): module · Use-case orchestration boundary · `application/build.gradle`
- [Use Cases](https://github.com/dmertins/video-catalog-admin/blob/main/application/build.gradle): orchestration · Coordinates input, domain, and transactions · `application/build.gradle`

### Infrastructure

Technical adapters and integrations

- [Infrastructure Module](https://github.com/dmertins/video-catalog-admin/blob/main/infrastructure/build.gradle): module · Outer technical adapter boundary · `infrastructure/build.gradle`
- [Adapters](https://github.com/dmertins/video-catalog-admin/blob/main/infrastructure/build.gradle): adapter layer · Persistence, services, and runtime wiring · `infrastructure/build.gradle`

## Connections

- Conventions → Domain Module: configures · Applies shared Gradle conventions to the domain module
- Conventions → Application Module: configures · Applies shared Gradle conventions to the application module
- Conventions → Infrastructure Module: configures · Applies shared Gradle conventions to the infrastructure module
- Domain Module → DDD Primitives: contains · Domain module exposes the reusable DDD base types
- Domain Module → Validation Core: contains · Domain module contains validation contracts and handlers
- Domain Module → Domain Errors: contains · Domain module defines the business error model
- Domain Module → Pagination: contains · Domain module models paged retrieval as a domain concept
- DDD Primitives → Category: supports · DDD primitives underpin the category aggregate
- DDD Primitives → Category ID: supports · Identifier abstraction is specialized by category identity
- Category → Category Rules: validated by · Category business rules are enforced through domain validation
- Category → Category Query: searched with · Search use cases are shaped by the category query model
- Category → Category Gateway: exposes · Domain publishes a gateway port for category access
- Category Rules → Throwing Handler: reports to · Validation problems are collected and thrown through a handler
- Application Module → Use Cases: contains · Application module hosts orchestration logic
- Use Cases → Category Gateway: uses · Use cases depend on the domain gateway abstraction
- Use Cases → Category: orchestrates · Use cases coordinate category domain behavior
- Infrastructure Module → Adapters: contains · Infrastructure module hosts technical implementations
- Adapters → Category Gateway: implements · Adapters realize the category gateway port
- Adapters → Use Cases: supports · Infrastructure provides execution-time support for application flows