Architecture

APiGen follows a modular, layered architecture designed for flexibility and maintainability.

High-Level Overview

Codegen Engine

The code generation engine transforms input schemas into target code.

Pipeline

Components

1. Schema Parser (SqlSchemaParser)

   • Parses SQL DDL statements
   • Extracts tables, columns, constraints
   • Identifies relationships (FK, M2M)

2. Model Builder

   • Converts parsed schema to internal model
   • Resolves naming conventions
   • Builds relationship graph

3. Template Engine

   • Uses Mustache templates
   • Language-specific templates per target
   • Supports custom template overrides

4. Code Generator

   • Orchestrates the generation process
   • Manages file output
   • Handles post-processing

Core Library Architecture

The runtime library follows Clean Architecture / Hexagonal Architecture.

Package Structure

com.jnzader.apigen.core/
├── domain/
│   ├── entity/          # Base entities (AuditableEntity, etc.)
│   ├── event/           # Domain events
│   └── exception/       # Domain exceptions
├── application/
│   ├── dto/             # Data Transfer Objects
│   ├── mapper/          # MapStruct mappers
│   ├── service/         # Service interfaces & impl
│   └── util/            # Utilities
└── infrastructure/
    ├── controller/      # REST controllers
    ├── repository/      # JPA repositories
    ├── config/          # Spring configuration
    └── filter/          # Request filters

Security Architecture

Event-Driven Architecture

APiGen supports domain events for loose coupling.

Event Types

• EntityCreatedEvent<T> - After entity creation
• EntityUpdatedEvent<T> - After entity update
• EntityDeletedEvent<T> - After entity deletion (soft/hard)

Caching Strategy

Multi-level caching for optimal performance.

Design Decisions

Why Mustache for Templates?

• Logic-less: Keeps templates simple
• Language-agnostic: Works for any output language
• Fast: Minimal overhead
• Debuggable: Easy to trace issues

Why Clean Architecture?

• Testability: Business logic isolated from infrastructure
• Flexibility: Easy to swap implementations
• Maintainability: Clear boundaries and responsibilities

Why Multi-Module?

• Separation of concerns: Each module has single responsibility
• Optional features: Include only what you need
• Independent versioning: Modules can evolve separately