# AuDB Architecture
**AuDB** (Application Database) - Compile-time database application framework
**Version:** 0.1.0
**Date:** October 2025
**Status:** Initial Design
---
## Vision
AuDB is a compile-time framework that transforms database queries and schemas into optimized, type-safe Rust applications with embedded databases. Instead of interpreting queries at runtime, AuDB compiles everything at build time into a single, deployable binary.
**Key Principles:**
- **Compile-time everything**: Parse, optimize, and validate at build time
- **Zero runtime overhead**: No query parsing, no schema validation at runtime
- **Type safety**: Compile-time type checking for queries and data
- **Single binary**: Database + queries + server in one executable
- **Multi-language**: Support HyperQL, SQL, Cypher, and more
---
## The Gold File Format (`.au`)
The core innovation of AuDB is the **gold file** (`.au`) - a universal container format for queries, schemas, configuration, and data.
### Why "Gold"?
- `.au` is the chemical symbol for gold
- Gold files are the "gold standard" source of truth
- Premium, valuable, and pure - like your data
### Gold File Structure
Gold files use a block-based format similar to Terraform HCL:
```au
// app.au - Application configuration
config database {
path = "./data"
engine = "manifold"
}
config server {
host = "0.0.0.0"
port = 8080
framework = "axum"
}
```
```au
// users.au - User domain
schema User {
id: EntityId
name: String
email: String
age: Integer
created_at: Timestamp
}
query get_user(id: EntityId) -> User {
language = "hyperql"
---
SELECT * FROM users WHERE id = :id
---
}
query list_users(min_age: Integer, limit: Integer) -> Vec<User> {
language = "hyperql"
---
SELECT id, name, email, age
FROM users
WHERE age > :min_age
ORDER BY name
LIMIT :limit
---
}
endpoint GET "/api/users/:id" {
query = get_user
auth = true
}
endpoint GET "/api/users" {
query = list_users
params {
min_age = query.min_age
limit = query.limit
}
}
```
### Multi-Language Support
Gold files support multiple query languages:
```au
// Multi-language queries
query get_user_sql(id: EntityId) -> User {
language = "sql"
---
SELECT * FROM users WHERE id = $1
---
}
query get_user_cypher(id: EntityId) -> User {
language = "cypher"
---
MATCH (u:User {id: $id}) RETURN u
---
}
query get_user_hyperql(id: EntityId) -> User {
language = "hyperql"
---
SELECT * FROM users WHERE id = :id
---
}
```
### Schema Formats
Support multiple schema formats:
```au
// JSON Schema
schema User {
format = "json-schema"
---
{
"type": "object",
"properties": {
"id": {"type": "string"},
"name": {"type": "string"},
"email": {"type": "string"}
}
}
---
}
// TypeScript-like
schema User {
format = "typescript"
---
interface User {
id: string;
name: string;
email: string;
}
---
}
// Rust-like (default)
schema User {
id: EntityId
name: String
email: String
}
```
---
## Crate Structure
AuDB follows the Manifold pattern with core in `src/` and sub-crates in `crates/`:
```
audb/
├── src/ # Core AuDB library
│ ├── lib.rs
│ ├── parser/ # Gold file parser
│ ├── model/ # Project model (schemas, queries, config)
│ ├── schema/ # Schema system
│ ├── validation/ # Validation and type checking
│ └── project/ # Project management
│
├── crates/
│ ├── audb-codegen/ # Code generation (IR → Rust)
│ ├── audb-build/ # Build system integration
│ ├── audb-cli/ # Command line interface
│ └── audb-runtime/ # Minimal runtime for generated code
│
├── ARCHITECTURE.md # This file
├── Cargo.toml
└── README.md
```
---
## Core Library (`src/`)
### Parser Module (`src/parser/`)
Parses `.au` gold files into an AST:
```rust
pub struct GoldParser;
impl GoldParser {
pub fn parse_file(path: &Path) -> Result<GoldFile>;
pub fn parse_str(content: &str) -> Result<GoldFile>;
}
pub struct GoldFile {
pub blocks: Vec<Block>,
}
pub enum Block {
Schema(SchemaBlock),
Query(QueryBlock),
Config(ConfigBlock),
Endpoint(EndpointBlock),
Data(DataBlock),
}
```
### Model Module (`src/model/`)
Internal representation of the project:
```rust
pub struct Project {
pub name: String,
pub version: String,
pub schemas: HashMap<String, Schema>,
pub queries: HashMap<String, Query>,
pub config: Config,
pub endpoints: Vec<Endpoint>,
}
pub struct Query {
pub name: String,
pub language: QueryLanguage,
pub source: String,
pub params: Vec<Parameter>,
pub return_type: Type,
}
pub enum QueryLanguage {
HyperQL,
SQL,
Cypher,
Custom(String),
}
```
### Schema Module (`src/schema/`)
Schema system supporting multiple formats:
```rust
pub struct Schema {
pub name: String,
pub format: SchemaFormat,
pub fields: Vec<Field>,
}
pub enum SchemaFormat {
Native, // Rust-like syntax
JsonSchema,
TypeScript,
Rust,
}
pub struct Field {
pub name: String,
pub field_type: Type,
pub nullable: bool,
pub default: Option<Value>,
}
```
### Validation Module (`src/validation/`)
Validate queries against schemas at compile time:
```rust
pub struct Validator;
impl Validator {
pub fn validate_project(project: &Project) -> Result<ValidationReport>;
pub fn validate_query(query: &Query, schemas: &HashMap<String, Schema>) -> Result<()>;
pub fn check_types(query: &Query, schema: &Schema) -> Result<()>;
}
```
---
## Sub-Crates
### `audb-codegen` - Code Generation
Generates Rust code from the project model:
```rust
pub struct CodeGenerator {
project: Project,
options: CodeGenOptions,
}
impl CodeGenerator {
pub fn new(project: Project) -> Self;
pub fn generate_schema_types(&self) -> TokenStream;
pub fn generate_query_functions(&self) -> TokenStream;
pub fn generate_server(&self) -> TokenStream;
pub fn generate_library(&self) -> TokenStream;
}
```
**Generated Code Example:**
```rust
// Generated from User schema
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct User {
pub id: EntityId,
pub name: String,
pub email: String,
pub age: i64,
}
// Generated from get_user query
pub fn get_user(db: &Database, id: EntityId) -> Result<User> {
// Pre-compiled execution plan
let plan = ExecutionPlan::Filter { /* ... */ };
db.execute_plan(plan)
}
```
### `audb-build` - Build System Integration
Integrates with Cargo's build system:
```rust
// build.rs
fn main() {
audb_build::Builder::new()
.gold_dir("./gold")
.output_dir("./src/generated")
.generate()
.unwrap();
}
```
**Features:**
- Discovers all `.au` files in project
- Parses and validates them
- Generates Rust code
- Emits `cargo:rerun-if-changed` directives
- Compile-time error reporting
### `audb-cli` - Command Line Interface
User-facing tool for managing AuDB projects:
```bash
# Initialize new project
audb init my-api --template server
# Build project (compiles queries)
audb build
# Development mode (watch and rebuild)
audb dev
# Deploy (create optimized binary)
audb deploy --target docker
# Validate without building
audb check
```
**Commands:**
```rust
pub enum Command {
Init {
name: String,
template: Template,
},
Build {
release: bool,
},
Dev {
port: Option<u16>,
},
Deploy {
target: DeployTarget,
},
Check,
}
pub enum Template {
Server, // REST API server
Library, // Rust library
CLI, // Command-line tool
Minimal, // Minimal setup
}
```
### `audb-runtime` - Runtime Library
Minimal runtime support for generated code:
```rust
pub struct Database {
manifold: Manifold,
}
impl Database {
pub fn open(path: &str) -> Result<Self>;
pub fn execute_plan(&self, plan: ExecutionPlan) -> Result<Vec<Entity>>;
}
pub trait QueryExecutor {
fn execute(&self, db: &Database) -> Result<Self::Output>;
}
```
**Design Goal:** Keep runtime as small as possible. Most work done at compile time.
---
## Compilation Pipeline
```
Gold Files (.au)
↓
Parser (audb core)
↓
Project Model
↓
Validator
↓
Query Compiler (HyperQL/SQL/Cypher)
↓
Intermediate Representation (IR)
↓
Code Generator (audb-codegen)
↓
Rust Source Code
↓
Cargo Build
↓
Optimized Binary
```
**Compile-Time Operations:**
- Parse gold files
- Validate schemas and queries
- Type check all queries
- Optimize query plans
- Generate Rust code
- Inline constants
- Dead code elimination
**Runtime Operations:**
- Open database
- Execute pre-compiled plans
- Return typed results
---
## Project Structure (User-Facing)
```
my-api/
├── gold/ # Gold files
│ ├── app.au # Application config
│ ├── users.au # User domain
│ ├── posts.au # Post domain
│ └── auth.au # Authentication
│
├── src/
│ ├── main.rs # Application entry point
│ └── generated/ # Generated by audb-build
│ ├── mod.rs
│ ├── schemas.rs
│ ├── queries.rs
│ └── server.rs
│
├── build.rs # Calls audb-build
├── Cargo.toml
└── README.md
```
---
## Templates
### Server Template
```au
// Initialized by: audb init my-api --template server
config database {
path = "./data"
engine = "manifold"
}
config server {
host = "0.0.0.0"
port = 8080
framework = "axum"
}
schema Example {
id: EntityId
name: String
}
query list_examples() -> Vec<Example> {
language = "hyperql"
---
SELECT * FROM examples
---
}
endpoint GET "/api/examples" {
query = list_examples
}
```
### Library Template
```au
// Initialized by: audb init my-lib --template library
config database {
path = "./data"
engine = "manifold"
}
config library {
name = "MyDatabase"
public = true
}
schema User {
id: EntityId
name: String
}
query get_user(id: EntityId) -> User {
language = "hyperql"
---
SELECT * FROM users WHERE id = :id
---
}
```
---
## Performance Goals
### Compile-Time vs Runtime
**Traditional Database (Runtime):**
- Parse query: ~100μs
- Optimize: ~50μs
- Type check: ~20μs
- Execute: ~10μs
- **Total: ~180μs per query**
**AuDB (Compile-Time):**
- Parse query: 0μs (done at build)
- Optimize: 0μs (done at build)
- Type check: 0μs (done at build)
- Execute: ~10μs
- **Total: ~10μs per query**
**Speedup: ~18x for simple queries, up to 100x for complex queries**
### Memory Usage
**Traditional:**
- Query cache: 10MB
- Schema cache: 5MB
- Parser state: 2MB
- **Total: ~17MB overhead**
**AuDB:**
- Runtime library: ~500KB
- **Total: ~500KB overhead**
**Memory savings: ~97%**
---
## Future Features
### Phase 1 (MVP)
- [x] Gold file parser
- [ ] HyperQL query support
- [ ] Basic schema system
- [ ] Code generation for queries
- [ ] CLI with init/build commands
- [ ] Server template
### Phase 2 (Multi-Language)
- [ ] SQL query support
- [ ] Cypher query support
- [ ] Multiple schema formats
- [ ] Library template
- [ ] CLI template
### Phase 3 (Advanced)
- [ ] Hot reload in dev mode
- [ ] Query result caching
- [ ] Migration system
- [ ] Data seeding
- [ ] Testing framework
### Phase 4 (Production)
- [ ] Docker deployment
- [ ] Kubernetes deployment
- [ ] Monitoring integration
- [ ] Distributed queries
- [ ] Multi-database support
---
## Design Decisions
### Why Gold Files Instead of YAML?
**YAML Problems:**
- No syntax highlighting for embedded queries
- Difficult to validate structure
- Poor error messages
- Not extensible
**Gold File Benefits:**
- Language-agnostic blocks
- Clear syntax boundaries
- Extensible block types
- Rich metadata support
- Better tooling potential
### Why Compile-Time?
**Benefits:**
- Type safety (catch errors at compile time)
- Performance (no runtime parsing)
- Security (no SQL injection)
- Simplicity (no query cache, no parser in prod)
**Trade-offs:**
- Longer build times
- Less dynamic (can't construct queries at runtime)
- Requires rebuild for query changes
**Decision:** For most applications, the benefits far outweigh the trade-offs.
### Why Multi-Language Support?
**Rationale:**
- Users know SQL, Cypher, or other languages
- Migration path from existing systems
- Best language for each use case
- Future-proof (support new languages easily)
**Implementation:**
- Each language has its own parser
- All compile to same IR
- Code generation language-agnostic
- Consistent type system across languages
---
## Success Criteria
**MVP Success:**
- Can parse gold files
- Can generate working Rust code from HyperQL queries
- Can build single-binary server
- 10x+ performance vs runtime execution
- Type-safe APIs
**Production Ready:**
- Supports HyperQL, SQL, Cypher
- Multiple deployment targets
- Comprehensive documentation
- Real-world usage examples
- Community adoption
---
## Conclusion
AuDB represents a paradigm shift in database application development. By moving all the complexity to compile time, we get:
- **Performance**: 10-100x faster than runtime systems
- **Safety**: Compile-time type checking
- **Simplicity**: Single binary deployment
- **Flexibility**: Multi-language, multi-paradigm
The gold file format (`.au`) provides a clean, extensible way to define everything about your database application in one place.
**Status: Ready to build the future of compiled database applications.**