Static Analysis Architecture

How Geni reconstructs your API specification without booting your application.

Two-Layer Architecture

Geni separates documentation generation into two distinct, decoupled layers:

[ Laravel Host Application ]
           │
           │ (Only touchpoint: Route Collection)
           ▼
┌────────────────────────────────────────────────────────┐
│               Geni\Laravel                             │
│   - GeniServiceProvider (registers routes & commands)  │
│   - RouteDiscoverer (extracts route URIs & methods)    │
│   - Controllers & Middleware (Docs UI, Auth, MCP)      │
└──────────────────────────┬─────────────────────────────┘
                           │ DiscoveredRoute descriptors
                           ▼
┌────────────────────────────────────────────────────────┐
│               Geni\Inference                           │
│   - SchemaReader (offline migration AST analyzer)      │
│   - ActionAstAcquirer (controller & closure ASTs)      │
│   - ValidationRuleExtractor & SchemaMapper             │
│   - ResourceResponseInferer & ResponseTypeResolver     │
│   - DocumentAssembler (produces OpenApiDocument)       │
└────────────────────────────────────────────────────────┘

1. Geni\Laravel (The Integration Bridge)

This namespace contains the only code that touches Laravel runtime components:

• RouteDiscoverer: Reads the Laravel RouteCollection to find registered route URIs, HTTP methods, route names, and middleware.
• GeniServiceProvider: Registers console commands (geni:export, geni:check, etc.) and HTTP routes for the docs portal.
• BladeRenderer: Renders the documentation portal view.

2. Geni\Inference (The Engine)

The inference layer is strictly framework-free:

• It never imports Illuminate\* classes.
• It uses nikic/php-parser to parse PHP code into Abstract Syntax Trees (AST).
• It analyzes controller methods, Form Requests, resources, and migrations purely by inspecting AST nodes.
• Because it is framework-free, it can be tested in isolation and never causes side-effects during analysis.

Schema Discovery Pipeline

When generating an OpenAPI specification, Geni executes the following steps:

1. Migration Replay

   SchemaReader parses all migration files in timestamp order. It tracks table creations, column definitions, column alterations, foreign keys, and dropped columns into an in-memory DatabaseSchema representation.

2. Route Discovery

   RouteDiscoverer filters registered routes by prefix (e.g. api/) or a custom resolver closure.

3. AST Acquisition

   ActionAstAcquirer locates the controller source file and isolates the target method AST node, along with its namespace and use import map.

4. Parameter Inference

   PathParameterInferer matches URI route parameters against model route keys and database columns. Query parameters are extracted from request accessors or Spatie QueryBuilder calls.

5. Request Body Inference

   ValidationRuleExtractor inspects Form Request rules() methods, controller inline validate() calls, or Spatie Data DTO properties, and maps them to JSON Schema via ValidationRuleSchemaMapper.

6. Response Inference

   ResourceResponseInferer inspects return statements (JsonResource, response()->json(), Data::from(), Eloquent models) and type hints to infer 200/201/204 response schemas.

7. Annotation Merging

   PhpDocAnnotationParser and AttributeAnnotationReader read explicit overrides (e.g., #[Response], @response, #[QueryParameter]) and merge them over inferred data.