Backend AI API — Code Generators Architecture

Purpose: Guide for AI agents extending or maintaining backend-ai-api code generators.
Updated: March 2026 — Post Global Engineering Standard refactor (Session 214–215)

Overview

backend-ai-api (port 3001) hosts AI workloads and code generation. The generators produce:

• Module code: Nx library files from ModuleSpec (entities, actions, embeddables)
• Platform code: Angular app shell from UniverseConfig (standalone deployable)

Generator Structure

APIs/backend-ai-api/src/app/workflow/generators/
├── module-code-generator.service.ts    # Orchestrator — delegates to sub-generators
├── module-project-config.generator.ts  # Nx config (project.json, tsconfig, jest)
├── module-crud-generator.ts            # CRUD actions + embeddables from entities
├── module-entity.generator.ts           # Entity model interfaces
├── module-action.generator.ts           # Action classes
├── module-embeddable.generator.ts      # Embeddable components (TS + HTML + SCSS)
├── module-module-class.generator.ts    # Module class + manifest
├── module-index.generator.ts            # Barrel exports
├── module-embed-template.generator.ts  # HTML templates
├── module-spec.types.ts                # ModuleSpec, EntitySpec, etc.
│
├── platform-code-generator.service.ts  # Orchestrator — delegates to sub-generators
├── platform-config.generator.ts        # package.json, tsconfig, angular.json, environment
├── platform-app.generator.ts            # main.ts, app.config, app.routes
├── platform-component.generator.ts     # app.component, layout templates
├── platform-navigation.generator.ts    # navigation, home page, module pages
├── platform-assets.generator.ts         # index.html, styles, _redirects, README
├── platform-spec.types.ts              # UniverseConfig, ModuleReference, etc.
│
└── README.md                            # Extension guide (this file's companion)

Segregation Rules

• Orchestrators (*-code-generator.service.ts): Thin — import and call sub-generators
• Sub-generators: Pure functions or small classes — one concern per file
• Types: In *-spec.types.ts — never inline in generators
• Target: No file >500 lines

Extending

New module generator

1. Create module-<concern>.generator.ts
2. Export functions (e.g. generateX(spec: ModuleSpec): GeneratedFile)
3. Import in module-code-generator.service.ts and call generateModule()

New platform generator

1. Create platform-<concern>.generator.ts
2. Export functions
3. Import in platform-code-generator.service.ts and call generatePlatform()

New spec field

1. Update module-spec.types.ts or platform-spec.types.ts
2. Update any generators that consume it

Import Conventions

• Use platform-spec.types for UniverseConfig, ModuleReference (e.g. ssr-config-generator.service.ts)
• Re-export types from orchestrator for backward compatibility

References

• APIs/backend-ai-api/src/app/workflow/generators/README.md — in-repo extension guide
• Global Engineering Standard