> ## Documentation Index
> Fetch the complete documentation index at: https://geni.masiting.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<Steps>
  <Step title="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.
  </Step>

  <Step title="Route Discovery">
    `RouteDiscoverer` filters registered routes by prefix (e.g. `api/`) or a custom resolver closure.
  </Step>

  <Step title="AST Acquisition">
    `ActionAstAcquirer` locates the controller source file and isolates the target method AST node, along with its namespace and `use` import map.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="Response Inference">
    `ResourceResponseInferer` inspects return statements (`JsonResource`, `response()->json()`, `Data::from()`, Eloquent models) and type hints to infer 200/201/204 response schemas.
  </Step>

  <Step title="Annotation Merging">
    `PhpDocAnnotationParser` and `AttributeAnnotationReader` read explicit overrides (e.g., `#[Response]`, `@response`, `#[QueryParameter]`) and merge them over inferred data.
  </Step>
</Steps>