Architecture
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.
System Overview
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
The ORM owns its metadata locally (generated an5Metadata.ts) and never imports from
the generated client. The client is generated from the ORM, and adapters receive
metadata only when it is passed explicitly.
Repository Roles
| Repository |
Role |
Key Capabilities |
| an5Adapters |
Runtime Execution Engine & Query Builder |
Provider-based SQL (MSSQL, Postgres, MySQL, SQLite), Google Sheets, and Vector Database execution (NBase, Qdrant, Chroma, Pinecone, Weaviate, Milvus), Query Builder (parseWhere, buildOrderBy, quote), executorFromAdapter bridge, connection pooling, and multi-language sources (TS, Python, .NET, Go, Rust, Java, Kotlin, Swift). |
| an5Orm |
Schema, Generator & Migrations |
Schema parser, multi-language code generator (generator/), database introspection (pull.ts), schema drift & migrations (migrate.ts, migration-core.ts), schema push (push.ts), and generic seeder runner (seed.ts). |
| 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. |
| an5Agent |
AI Agent Library |
7 schema-driven tools: schema, query, database, codegen, retrieve, task, analyzeSchema |
| an5Cli |
Workspace Automation & Release |
Workspace release (ws), changelog generation, LLM-powered commits, local management UI |
| an5OrmVScode |
Editor Extension & MCP Server |
Syntax highlighting, formatter, snippets for .an5 files, and native Model Context Protocol (MCP) server. |
| an5Schema |
Schema Source |
Sample .an5 model definitions |
| an5Tasks |
Task Manager |
Genkit v1.42+ flows, LLM review parsing, task CRUD, tools for agent integration |
| an5example |
Reference Examples |
Multi-dialect CRUD suite, browser (sql.js) support, runnable TypeScript/Go/.NET/Python/Rust/Java/Kotlin/Swift client examples |
| an5Site |
Landing Page |
Static site source (index.html + style.css + main.js) for https://an5orm.github.io, registered as an5-site npm workspace |
| an5Docs |
Documentation Site |
Jekyll documentation site serving 670+ pages with responsive UI, context switching, and SEO audit tooling |
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 (constructed directly from the DATABASE_URL-derived config) for DB operations |
an5Orm/generator |
an5Client/* |
Writes generated files |
an5Orm/generator |
an5Schema/ |
Reads .an5 definitions |
an5Cli |
an5Tasks |
Dynamic require() for task operations |
| Tool |
Actions |
Description |
schema |
list, describe, relations |
Explore data models |
| Tool |
Actions |
Description |
query |
generate, explain, validate |
Work with SQL queries |
| Tool |
Actions |
Description |
database |
execute, describe, health |
Database operations |
| 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 |
| Tool |
Actions |
Description |
retrieve |
schema, queries |
Semantic search |
| Tool |
Actions |
Description |
task |
create, list, update, delete |
Manage tasks |
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
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 |
At runtime the active LLM/embedding config can be read and updated through the
@an5/adapters config API (getLlmConfig/setLlmConfig,
getEmbeddingConfig/setEmbeddingConfig).
Technology Stack
- Runtime: Node.js 18+
- Language: TypeScript
- Database: SQL Server (primary), PostgreSQL, MySQL, SQLite
- AI Framework: Google Genkit v1.39
- Build Tool: npm workspaces
- Testing: Node built-in test runner (
node test/*.test.js)
- Documentation: Jekyll (GitHub Pages)