adding readmes

Author: xav-db

helix-db/src/helixc/analyzer/README.md

@@ -1,3 +1,41 @@
-# Interpreter
+# Analyzer Module
 
-The Interpreter takes in the AST and 
+## Overview
+The analyzer module performs static analysis and type checking on the HelixQL AST, ensuring queries are grammatically and semantically correct before code generation.
+
+## Structure
+
+### Core Components
+- **`mod.rs`** - Main analyzer entry point, orchestrates validation passes
+- **`types.rs`** - Type system definitions and type inference structures
+- **`diagnostic.rs`** - Diagnostic messages and error reporting
+- **`error_codes.rs`** - Error code definitions and messages
+- **`errors.rs`** - Error handling utilities
+- **`fix.rs`** - Auto-fix suggestions for common errors
+- **`pretty.rs`** - Pretty printing utilities for diagnostics
+- **`utils.rs`** - Helper functions for analysis
+
+### Validation Methods (in `methods/`)
+- **`schema_methods.rs`** - Schema validation and field lookup building
+- **`query_validation.rs`** - Query structure and parameter validation
+- **`migration_validation.rs`** - Schema migration consistency checks
+- **`statement_validation.rs`** - Statement-level validation
+- **`traversal_validation.rs`** - Graph traversal operation validation
+- **`graph_step_validation.rs`** - Individual graph step validation
+- **`object_validation.rs`** - Object literal and remapping validation
+- **`infer_expr_type.rs`** - Expression type inference
+- **`exclude_validation.rs`** - Field exclusion validation
+
+## Analysis Flow
+
+1. **Input**: Parsed AST from the parser module
+2. **Schema Validation**: Verifies schema definitions are valid
+3. **Migration Validation**: Ensures migrations are consistent across versions
+4. **Query Validation**: Type-checks queries against schemas
+5. **Output**: Diagnostics (errors/warnings) and validated AST for code generation
+
+
+## Error Handling
+- Error codes provide consistent, searchable error identification
+- Diagnostics include source location for precise error reporting
+- Fix suggestions help users resolve common issues

helix-db/src/helixc/generator/README.md

@@ -0,0 +1,35 @@
+# Generator Module
+
+## Overview
+The generator module transforms the validated HelixQL AST into executable Rust code, creating type-safe graph database operations.
+
+## Structure
+
+### Core Components
+- **`mod.rs`** - Main generator entry point, defines output structure
+- **`utils.rs`** - Helper functions and code generation utilities
+
+### Code Generation Methods (by domain)
+- **`schemas.rs`** - Generates Rust structs for nodes, edges, and vectors
+- **`queries.rs`** - Generates query functions with proper signatures
+- **`migrations.rs`** - Generates migration code for schema evolution
+- **`statements.rs`** - Generates statement execution code
+- **`traversal_steps.rs`** - Generates graph traversal operations
+- **`source_steps.rs`** - Generates source operations (add_n, add_e, n_from_id, n_from_type, etc.)
+- **`bool_ops.rs`** - Generates boolean expression evaluators
+- **`object_remappings.rs`** - Generates object transformation code
+- **`return_values.rs`** - Generates return value processing
+- **`tsdisplay.rs`** - TypeScript display utilities
+
+## Generation Flow
+
+1. **Input**: Validated AST from the analyzer module
+2. **Schema Generation**: Creates Rust structs for all schema types
+3. **Query Generation**: Transforms queries into Rust functions
+4. **Migration Generation**: Creates migration execution code
+5. **Output**: Complete Rust source code ready for compilation
+
+## Code Generation Patterns
+- Uses Rust's `Display` trait for code generation
+- Maintains proper indentation and formatting
+- Generates idiomatic Rust code with appropriate error handling