AN5 Architecture
Overview
Multi-repository monorepo providing a SQL Server schema-driven development platform with multi-language code generation, provider-based runtime adapters, and AI-powered agent assistance.
flowchart TB
subgraph Sources["Schema & Tooling"]
Schema["an5Schema/<br/>(schema src)"]
Vscode["an5OrmVScode/<br/>(editor tooling)"]
Cli["an5Cli/<br/>(automation)"]
end
subgraph Core["Core & Generation"]
Orm["an5Orm/<br/>(generator)"]
Client["an5Client/<br/>(generated)"]
Adapters["an5Adapters/<br/>(runtimes)"]
end
subgraph AI["AI & Agent Layer"]
Agent["an5Agent/<br/>(AI tools)"]
Tasks["an5Tasks/<br/>(Genkit flows)"]
end
Schema -.-> Orm
Cli -.-> Adapters
Orm --> Client
Client -->|optional metadata| Adapters
Agent --> Adapters
Tasks --> Agent
Repository Roles
| Repo | Role | Key Capabilities |
|---|---|---|
| an5Orm | Schema, Generator & Migrations | Schema parser, multi-language code generator, database introspection (pull.ts), schema push (push.ts), migrations (migrate.ts), and seeder runner |
| an5Client | Generated artifacts | TypeScript model interfaces + metadata, Python dataclasses + metadata, .NET entity classes, Go structs/client, Rust models/client crate, Java JavaBeans + An5DbContext, Kotlin data classes + An5Db, and Swift structs + An5Db |
Data Flow
flowchart LR
Dev["Developer writes .an5<br/>(Schema definitions)"] --> Gen["an5Orm/generator<br/>(Multi-language generator)"]
Gen --> Client["an5Client/<br/>(TS · Python · .NET · Go · Rust)"]
Client --> Adapters["an5Adapters/<br/>(DB runtimes & metadata)"]
Adapters --> Agent["an5Agent/<br/>(7 schema-driven tools)"]
Agent --> Cli["an5Cli/<br/>(Workspace orchestration)"]
Cross-Repo Connections
| Source | Target | Mechanism |
|---|---|---|
an5Agent |
an5Adapters |
Dynamic require() via relative path |
an5Agent |
an5Tasks |
Dynamic require() — bridges Genkit tools into agent Tool interface |
an5Agent |
an5Client |
Metadata file read for model info |
an5Agent |
an5Schema |
Directory scan for .an5 files |
| generated clients | an5Adapters |
Optional metadata injection for model/table mapping |
an5Orm |
own an5Metadata.ts |
Local metadata require — the core never imports the generated client (the client is generated from the ORM) |
an5Orm |
an5Adapters |
An5Adapter (via createAn5Adapter) for DB operations |
an5Orm/generator |
an5Client/* |
Writes generated files |
an5Orm/generator |
an5Schema/ |
Reads .an5 definitions |
an5Cli |
an5Tasks |
Dynamic require() for task operations |
Agent Tools (7 consolidated)
Schema (1 tool with 3 actions)
| Tool | Actions | Description |
|——|———|————-|
| schema | list, describe, relations | Explore data models |
Query (1 tool with 3 actions)
| Tool | Actions | Description |
|——|———|————-|
| query | generate, explain, validate | Work with SQL queries |
Database (1 tool with 3 actions)
| Tool | Actions | Description |
|——|———|————-|
| database | execute, describe, health | Database operations |
Code Generation (2 tools)
| Tool | Description |
|——|————-|
| generateClientCode | Generate TS/Python/.NET/Go/Rust client code |
| generateCode | Schema-grounded application code or context for the calling model |
| analyzeSchema | Analyze schema for design issues |
RAG (1 tool with 2 actions)
| Tool | Actions | Description |
|——|———|————-|
| retrieve | schema, queries | Semantic search |
Task Management (1 tool with 4 actions)
| Tool | Actions | Description |
|——|———|————-|
| task | create, list, update, delete | Manage tasks |
LLM Integration
| Provider | Env Variable | Default Model |
|---|---|---|
| OpenAI | OPENAI_API_KEY / LLM_API_KEY |
gpt-4o-mini |
| Gemini | GEMINI_API_KEY / LLM_API_KEY |
gemini-2.5-flash |
| Custom | LLM_ENDPOINT |
llama3 |
Genkit Integration
| Module | Role | Features |
|---|---|---|
an5Tasks |
Tool provider | ai.defineTool(), ai.defineFlow(), ai.generate() |
an5Agent |
Tool consumer | Bridges Genkit tools into agent Tool interface via task-tools.ts |
Genkit Tools (defined in an5Tasks, used by an5Agent)
| Tool | Input | Output |
|---|---|---|
createTask |
type, description, file? | Task object |
listTasks |
workspaceDir, status?, priority? | Task[] |
updateTask |
workspaceDir, taskId, status?, priority? | Task | null |
deleteTask |
workspaceDir, taskId | boolean |
Genkit Flows
| Flow | Description |
|---|---|
parseReviewToTasksFlow |
Regex-based task extraction from LLM reviews |
aiParseReviewToTasksFlow |
AI-powered task extraction using generate() |
Architecture: Genkit Bridge
flowchart TD
subgraph Consumer["An5Agent class (Consumer Interface)"]
direction LR
C1[".addTool(task)"]
C2[".executeTool('task', action)"]
end
subgraph Bridge["an5Agent/src/tools/task-tools.ts (Tool Bridge)"]
L["loadTasksModule()<br/>(dynamic import)"]
E["task.execute()<br/>(calls loaded module)"]
R["action: create / list / update / delete"]
end
subgraph Tasks["an5Tasks/src/index.ts (Genkit Tools)"]
direction LR
T1["ai.defineTool('createTask')"]
T2["ai.defineTool('listTasks')"]
T3["ai.defineTool('updateTask')"]
T4["ai.defineTool('deleteTask')"]
end
Consumer -->|"Tool interface"| Bridge
Bridge -->|"require()"| Tasks
Consumer -.->|"Genkit v1.39 flows"| Tasks
The bridge works by:
an5Tasksdefines Genkit tools withai.defineTool()an5Agent/src/tools/task-tools.tsconsolidates 4 tools into 1tasktoolan5Agentregisters all 8 tools inDEFAULT_TOOLSprocess()matches natural language → routes to appropriate tool/action