Skip to main content

forge Framework - Implementation Details

Overview​

This document provides detailed implementation information for all features in the forge framework.

Implementation Status​

✅ Fully Implemented Features​

1. Schema System​

Location: forge/schema/
Status: ✅ Complete

Implementation Details:

  • Complete field type system (Int64, Int32, String, Bool, Time, Date, DateTime, Float32, Float64, Decimal, Text, Email, URL, UUID, JSON, Bytes)
  • Complete field options (Required, Blank, Default, Primary, AutoIncrement, Unique, Index, MaxLength, MinLength, Choices, HelpText, VerboseName, DBColumn, DBType, DBIndex, DBCollation, DBComment, Generated, Validators, ValidationTag, Editable, AutoNow, AutoNowAdd)
  • Relationship definitions (ForeignKey, OneToOne, ManyToMany, OneToMany)
  • Model metadata (TableName, OrderBy, VerboseName, VerboseNamePlural, Indexes, UniqueTogether, Constraints, Permissions, DefaultPermissions)
  • Lifecycle hooks (BeforeSave, AfterSave, BeforeCreate, AfterCreate, BeforeUpdate, AfterUpdate, BeforeDelete, AfterDelete)
  • Constraint builders

Key Files:

  • schema.go - Core Schema interface
  • field.go - Field definitions
  • relation.go - Relationship definitions
  • meta.go - Model metadata
  • hooks.go - Lifecycle hooks
  • constraint_builder.go - Constraint builders

2. Code Generation​

Location: forge/codegen/
Status: ✅ Complete

Implementation Details:

  • AST-based schema parsing from Go source
  • Model struct generation with proper types
  • FieldExpr generation for type-safe field access
  • Manager generation with CRUD operations
  • QuerySet generation with type safety
  • Template-based code generation
  • Import management
  • Code formatting (goimports)
  • Error handling and validation

Key Files:

  • ast_parser.go - Go AST parser for schema extraction
  • generator.go - Main code generator
  • writer.go - Code file writer with formatting
  • templates.go - Code generation templates
  • templates/ - Template files

Generated Code:

  • Model structs with proper types and DB tags
  • FieldExpr definitions for type-safe field access
  • Manager with Create, Update, Delete, Get methods
  • QuerySet wrappers with full type safety
  • Field accessors and setters

3. ORM System​

Location: forge/orm/
Status: ✅ Complete (with some advanced features structure ready)

Implementation Details:

  • Type-safe QuerySet interface
  • Filter, Exclude, OrderBy, Limit, Offset, Distinct
  • All, Get, First, Last, Count, Exists
  • Select, Only, Defer (structure ready)
  • SelectRelated, PrefetchRelated (structure ready)
  • Aggregate, Annotate (structure ready)
  • Values, ValuesList (structure ready)
  • Update, Delete operations
  • Manager with CRUD operations
  • Field expressions with type safety
  • SQL builder with proper escaping
  • Update builder for type-safe updates
  • Set operations (Union, Intersection, Difference)

Key Files:

  • queryset.go - QuerySet implementation
  • manager.go - Manager implementation
  • field_expr.go - Field expressions
  • expression.go - Query expressions
  • sql_builder.go - SQL generation
  • update_builder.go - Update operations
  • aggregates.go - Aggregate functions (structure ready)
  • annotations.go - Annotations (structure ready)

4. Admin System​

Location: forge/admin/
Status: ✅ Complete

Implementation Details:

  • Type-safe Admin interface with generics
  • Complete Config system with all Django admin options
  • List view with pagination, filtering, searching, sorting
  • Detail view for viewing/editing objects
  • Form handling for create/update
  • Filter system (Boolean, Choice, Date, Number, Text, Related, Custom)
  • Widget system (Text, Textarea, Select, Checkbox, Radio, Date, Time, DateTime, File, Image, RichText, Autocomplete, RawID)
  • Actions system for bulk operations
  • Export functionality (CSV, JSON)
  • Inlines for related model editing
  • Fieldsets for form field grouping
  • Permission system
  • Complete HTTP handlers

Key Files:

  • admin.go - Admin interface
  • config.go - Admin configuration
  • list_view.go - List view
  • detail_view.go - Detail view
  • form_view.go - Form handling
  • filters.go, filters_advanced.go - Filter system
  • widgets.go, widgets_advanced.go - Widget system
  • actions.go - Actions
  • export.go - Export
  • inlines.go - Inlines
  • fieldsets.go - Fieldsets
  • permissions.go - Permissions
  • http/ - HTTP handlers

5. REST API Framework​

Location: forge/api/
Status: ✅ Complete

Implementation Details:

  • BaseViewSet with CRUD operations
  • Complete Serializer system with field types
  • Authentication backends (Token, JWT, Basic, Session, API Key)
  • Permission classes (AllowAny, IsAuthenticated, IsAdminUser, IsOwnerOrReadOnly, etc.)
  • Throttling (AnonRateThrottle, UserRateThrottle, ScopedRateThrottle)
  • Renderers (JSON, XML, YAML, HTML, CSV)
  • Parsers (JSON, XML, Form, MultiPart)
  • Filters (Field filtering, Search)
  • Pagination (PageNumber, LimitOffset)
  • Exception handling
  • Versioning support
  • Cache backends
  • OpenAPI documentation

Key Files:

  • viewset.go - ViewSet implementation
  • serializer.go - Serializer system
  • serializers/ - Field serializers
  • authentication/ - Auth backends
  • permissions/ - Permission classes
  • throttling/ - Rate limiting
  • renderers/ - Response renderers
  • parsers/ - Request parsers
  • filters/ - Field filtering
  • pagination.go - Pagination
  • exceptions/ - Exception handling
  • versioning/ - API versioning
  • caching/ - Cache backends
  • docs/ - OpenAPI documentation

6. Filter System​

Location: forge/filter/
Status: ✅ Complete

Implementation Details:

  • Type-safe FilterSet with generics
  • Base Filter interface
  • FilterSet implementation with AST support
  • Query string parser with multiple formats
  • AST representation for complex filters
  • Expression converter to ORM expressions
  • Multiple filter types (Boolean, Choice, Date, Number, Text, Related, Custom)
  • Filter widgets for UI
  • Security validation (field whitelist/blacklist, lookup restrictions)
  • Query optimization
  • Filter persistence and sharing
  • Custom filter registration

Key Files:

  • filter.go - Base filter interface
  • filterset.go - FilterSet implementation
  • parser.go - Query string parser
  • ast.go - AST representation
  • expression_converter.go - Expression conversion
  • filters/ - Filter implementations
  • widgets/ - Filter widgets
  • security.go - Security validation
  • optimizer.go - Query optimization
  • custom.go - Custom filter support
  • persistence.go - Filter persistence

7. Identity System​

Location: forge/identity/
Status: ✅ Complete

Implementation Details:

  • Complete User model with all Django-like fields
  • Session, Permission, Group, Token models
  • Repository pattern for data access (User, Session, Token, Permission, Group)
  • Service layer for business logic (User, Auth, Password, Permission)
  • Multiple authentication backends (Password, Token) with registry
  • Backend strategy pattern for extensibility
  • API serializers for all models
  • Complete HTTP handlers (register, login, logout, CRUD)
  • Authentication and authorization middleware
  • Password management with bcrypt and policies
  • Account security (lockout, expiration, verification)
  • Factory for complete system setup
  • Configuration system with password policies

Key Files:

  • models/ - User and related models
  • repository/ - Data access layer
  • service/ - Business logic services
  • backends/ - Authentication backends with registry
  • serializers/ - API serializers
  • handlers/ - HTTP handlers
  • middleware/ - Authentication and authorization middleware
  • factory.go - System setup
  • config/ - Configuration
  • router.go - Route registration

8. Database Layer​

Location: forge/db/
Status: ✅ Complete

Implementation Details:

  • Database connection wrapper with pooling
  • Multiple driver support (PostgreSQL, SQLite)
  • Transaction management with savepoints
  • Nested transaction support
  • Migration system integration
  • SQL builder integration
  • Connection health checks
  • Config-based connection setup

Key Files:

  • db.go - Database connection wrapper
  • transaction.go - Transaction management with savepoints
  • migrations.go - Migration integration

9. Migration System​

Location: forge/db/migrate/ and forge/migrate/
Status: ✅ Complete

Implementation Details:

  • AST-based schema parsing
  • State management and tracking
  • Change detection (15+ change types)
  • SQL generation for multiple dialects
  • Migration execution with transactions
  • Rollback support
  • Migration verification and drift detection
  • Dependency resolution
  • Checksum verification
  • Safety checks and validation
  • Dry-run mode
  • Recovery from failed migrations

Key Files:

  • migrate.go - Public API
  • generate/generator.go - Migration generation
  • generate/detector.go - Change detection
  • state/manager.go - State management
  • sql/builder.go - SQL generation
  • execute/executor.go - Migration execution
  • verify/ - Verification and drift detection

10. HTTP & Server​

Location: forge/server/
Status: ✅ Complete

Implementation Details:

  • Server wrapper
  • Router setup (chi)
  • Middleware stack (Request ID, Real IP, Recoverer, Logger, Session, CSRF, Authentication)
  • Request context
  • Response helpers
  • Security middleware
  • Static file serving
  • Health checks
  • Rate limiting

Key Files:

  • server.go - Server wrapper
  • router.go - Router setup
  • middleware.go - Middleware stack
  • context.go - Request context
  • response.go - Response helpers
  • security.go - Security middleware
  • static.go - Static file serving
  • health.go - Health checks
  • ratelimit.go - Rate limiting

11. Logging System​

Location: forge/log/
Status: ✅ Complete

Implementation Details:

  • Structured logging with zap
  • Multiple output formats (JSON, console)
  • Multiple outputs (console, file, remote)
  • Log levels
  • Sampling in production
  • Contextual logging
  • Log exporters
  • Log hooks

Key Files:

  • logger.go - Logger implementation
  • config.go - Logging configuration
  • encoder.go - Log encoders
  • exporters/ - Log exporters
  • hooks/ - Log hooks
  • middleware.go - Request logging

12. Configuration System​

Location: forge/config/
Status: ✅ Complete

Implementation Details:

  • Viper wrapper
  • YAML, JSON, env var support
  • Hierarchical configuration
  • Default values
  • Framework settings
  • Logging settings

Key Files:

  • config.go - Viper wrapper
  • settings.go - Framework settings
  • logging_settings.go - Logging settings

13. Validation System​

Location: forge/validate/
Status: ✅ Complete

Implementation Details:

  • go-playground/validator integration
  • Validation tag helpers
  • Schema integration
  • Custom validators

Key Files:

  • Validator wrapper
  • Validation tag helpers
  • Schema integration

14. Security System​

Location: forge/security/
Status: ✅ Complete

Implementation Details:

  • CSRF protection (gorilla/csrf)
  • XSS prevention
  • SQL injection prevention
  • Input sanitization

Key Files:

  • CSRF protection
  • XSS prevention
  • SQL injection prevention

15. CLI Tools​

Location: forge/cli/
Status: ✅ Complete

Implementation Details:

  • Project creation (forge new)
  • Code generation (forge generate)
  • Migrations (forge migrate)
  • Server (forge runserver)
  • Additional commands

Key Files:

  • root.go - CLI root
  • commands/ - CLI commands
  • templates/ - Project templates
  • core/ - Core CLI functionality

🚧 Partially Implemented Features​

Advanced ORM Features​

Location: forge/orm/
Status: 🚧 Structure Ready

Implementation Details:

  • SelectRelated/PrefetchRelated - Structure ready, implementation needed
  • Aggregates - Structure ready, implementation needed
  • Annotations - Structure ready, implementation needed
  • F() Expressions - Planned
  • Subqueries - Planned
  • Values/ValuesList - Structure ready, implementation needed

📋 Planned Features​

Planned work is tracked in GitHub issues and discussions so it stays current with real-world priorities.

Implementation Patterns​

Type Safety​

  • Generics used throughout for type safety
  • Interface-based design for extensibility
  • Builder pattern for fluent APIs

Code Generation​

  • AST-based parsing
  • Template-based generation
  • Type-safe generated code

Error Handling​

  • Structured errors
  • Error wrapping
  • Context-aware errors

Performance​

  • Connection pooling
  • Query optimization
  • Efficient data structures
  • Minimal allocations

Testing​

Test Coverage​

  • Unit tests for core functionality
  • Integration tests for workflows
  • E2E tests for critical paths

Test Infrastructure​

  • Test helpers
  • Mock framework
  • Test database management

Documentation​

Code Documentation​

  • Comprehensive code comments
  • API documentation
  • Usage examples

User Documentation​

  • Getting started guides
  • Feature documentation
  • API reference
  • Tutorials