Platform Architecture

APSO is a code generation platform that produces production-ready backend applications from a declarative schema.

System Overview

Core Components

Schema Parser

The schema parser reads and validates .apsorc files:

JSON Parsing - Load and parse the configuration file
Schema Validation - Validate against the APSO schema specification
Reference Resolution - Resolve entity and field references
Relationship Mapping - Build the relationship graph

Code Generator

The code generator transforms schema into code:

Template Types:

Entity templates (ORM models)
Controller templates (API endpoints)
Service templates (business logic)
DTO templates (data transfer objects)
Module templates (framework wiring)

Output Structure

Generated code follows a consistent structure:


generated-backend/
├── src/
│   ├── entities/           # ORM entity definitions
│   ├── modules/            # Feature modules
│   │   └── {entity}/
│   │       ├── controller  # HTTP handlers
│   │       ├── service     # Business logic
│   │       └── dto/        # Request/response schemas
│   ├── common/             # Shared utilities
│   ├── extensions/         # Your custom code
│   └── main.ts             # Application entry point
├── migrations/             # Database migrations
├── test/                   # Test files
└── .apsorc                 # Source schema

Data Flow

Request Lifecycle

Multi-Tenancy Flow

Code Generation Pipeline

1. Schema Ingestion


// Input: .apsorc
{
  "entities": [
    {
      "name": "Project",
      "fields": [
        { "name": "name", "type": "string", "required": true }
      ]
    }
  ]
}

2. AST Generation


// Intermediate representation
{
  entities: [{
    name: 'Project',
    tableName: 'projects',
    fields: [{
      name: 'name',
      type: 'string',
      tsType: 'string',
      sqlType: 'varchar(255)',
      required: true,
      validators: ['IsNotEmpty', 'MaxLength(255)']
    }]
  }]
}

3. Template Application


// Output: project.entity.ts
@Entity('projects')
export class Project {
  @PrimaryGeneratedColumn('uuid')
  id: string;
 
  @Column({ nullable: false })
  name: string;
}

Extension Points

Pre-Generation Hooks

Modify the schema before code generation:


// hooks/pre-generate.ts
export function beforeGenerate(schema: Schema): Schema {
  // Add audit fields to all entities
  return addAuditFields(schema);
}

Post-Generation Hooks

Process generated files:


// hooks/post-generate.ts
export function afterGenerate(files: GeneratedFile[]): void {
  // Run prettier on all files
  files.forEach(file => prettier.format(file));
}

Template Overrides

Override specific templates:


templates/
├── entity.hbs          # Custom entity template
└── controller.hbs      # Custom controller template

Performance Characteristics

Metric	Typical Value
Schema parsing	< 50ms
Code generation	< 2s for 50 entities
Hot reload	< 500ms
API response (simple)	< 20ms
API response (with joins)	< 100ms