omega-server/docs/ARCHITECTURE.md

# Architecture Documentation

## Overview

This document describes the architecture of the Bootstrap App, which follows clean architecture principles with clear separation of concerns, dependency injection, and modern security practices.

## Architecture Principles

### Clean Architecture
The application follows Uncle Bob's Clean Architecture principles:
- **Independence of Frameworks**: The architecture doesn't depend on specific frameworks
- **Testability**: Business rules can be tested without UI, database, or external services
- **Independence of UI**: The UI can change without changing the business rules
- **Independence of Database**: Business rules are not bound to the database
- **Independence of External Services**: Business rules know nothing about the outside world

### SOLID Principles
- **Single Responsibility**: Each class/module has one reason to change
- **Open/Closed**: Open for extension, closed for modification
- **Liskov Substitution**: Objects should be replaceable with instances of their subtypes
- **Interface Segregation**: Many client-specific interfaces are better than one general-purpose interface
- **Dependency Inversion**: Depend on abstractions, not concretions

## Layer Architecture

### 1. Presentation Layer (`controller/`)
**Responsibility**: Handle HTTP requests and responses
- Input validation and sanitization
- Request/response mapping
- Error handling and status codes
- Authentication and authorization checks

**Components**:
- Controllers for each domain
- Middleware for cross-cutting concerns
- Request/response DTOs

**Dependencies**: Service Layer

### 2. Business Logic Layer (`service/`)
**Responsibility**: Implement business rules and orchestrate operations
- Business rule validation
- Transaction management
- Cross-domain operations
- Business logic orchestration

**Components**:
- Service classes for each domain
- Business rule validators
- Transaction coordinators

**Dependencies**: Repository Layer, External Services

### 3. Data Access Layer (`repository/`)
**Responsibility**: Data persistence and retrieval
- Database operations
- Query optimization
- Data mapping
- Cache management

**Components**:
- Repository interfaces and implementations
- Database models
- Query builders

**Dependencies**: Database, Cache

### 4. Domain Layer (`model/`)
**Responsibility**: Core business entities and rules
- Domain entities
- Value objects
- Domain services
- Business rule definitions

**Components**:
- Entity models
- Validation rules
- Domain constants
- Business exceptions

**Dependencies**: None (should be isolated)

### 5. Infrastructure Layer (`utl/`)
**Responsibility**: External concerns and utilities
- Database configuration
- Logging
- Security utilities
- Configuration management
- External service integrations

**Components**:
- Database connection and migration
- Logging infrastructure
- Security middleware
- Configuration loaders
- Utility functions

## Component Interaction Flow

```
HTTP Request
     ↓
[Middleware Stack] ← Security, Logging, CORS
     ↓
[Controller] ← Request handling, validation
     ↓
[Service] ← Business logic, orchestration
     ↓
[Repository] ← Data access, persistence
     ↓
[Database/Cache] ← Data storage
```

## Dependency Injection

The application uses Uber Dig for dependency injection, providing:
- **Loose Coupling**: Components depend on interfaces, not implementations
- **Testability**: Easy to mock dependencies for testing
- **Configuration**: Centralized dependency configuration
- **Lifecycle Management**: Automatic instance management

### DI Container Structure
```go
// Database and core services
di.Provide(func() *gorm.DB { ... })
di.Provide(NewCache)

// Repositories
di.Provide(NewUserRepository)
di.Provide(NewRoleRepository)
// ...

// Services
di.Provide(NewUserService)
di.Provide(NewAuthService)
// ...

// Controllers
di.Invoke(NewUserController)
di.Invoke(NewAuthController)
// ...
```

## Security Architecture

### Authentication Flow
```
Client Request
     ↓
[CORS Middleware] ← Cross-origin validation
     ↓
[Security Headers] ← Security headers injection
     ↓
[Rate Limiting] ← Request rate validation
     ↓
[JWT Validation] ← Token verification
     ↓
[Permission Check] ← Authorization validation
     ↓
[Controller] ← Authorized request processing
```

### Security Layers
1. **Network Security**: CORS, security headers, HTTPS
2. **Authentication**: JWT token validation
3. **Authorization**: Role-based access control
4. **Input Security**: Sanitization, validation, size limits
5. **Audit Security**: Logging, monitoring, alerting

## Database Architecture

### Entity Relationships
```
Users
├── UserRoles (Many-to-Many with Roles)
├── AuditLogs (One-to-Many)
└── SecurityEvents (One-to-Many)

Roles
├── UserRoles (Many-to-Many with Users)
└── RolePermissions (Many-to-Many with Permissions)

Permissions
└── RolePermissions (Many-to-Many with Roles)

SystemConfig (Standalone)
```

### Base Model Pattern
All entities inherit from `BaseModel`:
```go
type BaseModel struct {
    ID          string    `json:"id" gorm:"primary_key"`
    DateCreated time.Time `json:"dateCreated"`
    DateUpdated time.Time `json:"dateUpdated"`
}
```

Benefits:
- Consistent ID generation (UUID)
- Automatic timestamp management
- Uniform audit trail
- Simplified queries

## API Architecture

### RESTful Design
- **Resource-based URLs**: `/api/v1/users/{id}`
- **HTTP Methods**: GET, POST, PUT, DELETE, PATCH
- **Status Codes**: Appropriate HTTP status codes
- **Content Negotiation**: JSON request/response format

### API Versioning
- **URL Versioning**: `/api/v1/`
- **Backward Compatibility**: Maintain older versions
- **Migration Path**: Clear upgrade documentation

### Response Format
```go
type APIResponse struct {
    Success bool        `json:"success"`
    Data    interface{} `json:"data,omitempty"`
    Message string      `json:"message,omitempty"`
    Error   string      `json:"error,omitempty"`
    Code    int         `json:"code,omitempty"`
}
```

### Pagination
```go
type PaginatedResponse struct {
    APIResponse
    Pagination PaginationResponse `json:"pagination"`
}
```

## Middleware Architecture

### Middleware Stack (Order Matters)
1. **Recovery**: Panic recovery and logging
2. **Security Headers**: OWASP security headers
3. **CORS**: Cross-origin resource sharing
4. **Rate Limiting**: Request rate limiting
5. **Request Logging**: HTTP request/response logging
6. **Authentication**: JWT token validation
7. **Authorization**: Permission validation
8. **Input Validation**: Request sanitization

### Security Middleware Components
- **Rate Limiter**: Token bucket algorithm with IP-based limits
- **Input Sanitizer**: XSS protection, SQL injection prevention
- **Content Validator**: Content-type and size validation
- **User Agent Validator**: Bot detection and blocking

## Configuration Architecture

### Configuration Layers
1. **Environment Variables**: Runtime configuration
2. **Database Config**: Dynamic configuration storage
3. **Default Values**: Fallback configuration
4. **Validation**: Configuration validation rules

### Configuration Categories
- **Security**: JWT secrets, encryption keys, password policies
- **Database**: Connection settings, migration options
- **API**: Rate limits, timeouts, CORS settings
- **Logging**: Log levels, retention policies
- **Features**: Feature flags, service toggles

## Error Handling Architecture

### Error Types
1. **Business Errors**: Domain rule violations
2. **Validation Errors**: Input validation failures
3. **System Errors**: Infrastructure failures
4. **Security Errors**: Authentication/authorization failures

### Error Propagation
```
Controller → Service → Repository
     ↓         ↓         ↓
  HTTP    Business   Data
  Error    Error     Error
```

### Error Response Format
```go
type HTTPError struct {
    Code    int                    `json:"code"`
    Message string                 `json:"message"`
    Details map[string]interface{} `json:"details,omitempty"`
}
```

## Logging Architecture

### Log Levels
- **DEBUG**: Detailed information for debugging
- **INFO**: General information about application flow
- **WARN**: Warning messages for potential issues
- **ERROR**: Error messages for failures
- **PANIC**: Critical errors that cause application termination

### Log Categories
1. **Application Logs**: General application flow
2. **HTTP Logs**: Request/response logging
3. **Security Logs**: Authentication, authorization events
4. **Audit Logs**: User actions and system changes
5. **Performance Logs**: Response times, resource usage

### Log Format
```
[TIMESTAMP] LEVEL [CALLER] MESSAGE
[2024-01-01 12:00:00] INFO [main.go:42] Starting application
```

## Caching Architecture

### Cache Layers
1. **Application Cache**: In-memory cache for frequently accessed data
2. **Database Cache**: GORM query result caching
3. **HTTP Cache**: Response caching for static content

### Cache Strategies
- **TTL-based**: Time-to-live expiration
- **LRU**: Least recently used eviction
- **Size-based**: Memory usage limits
- **Manual**: Explicit cache invalidation

## Testing Architecture

### Test Layers
1. **Unit Tests**: Individual component testing
2. **Integration Tests**: Component interaction testing
3. **API Tests**: End-to-end API testing
4. **Security Tests**: Security vulnerability testing

### Test Structure
```
test/
├── unit/           # Unit tests
├── integration/    # Integration tests
├── api/           # API tests
├── fixtures/      # Test data
└── helpers/       # Test utilities
```

### Mock Strategy
- **Interface Mocking**: Mock external dependencies
- **Database Mocking**: In-memory database for tests
- **HTTP Mocking**: Mock external API calls

## Scalability Considerations

### Horizontal Scaling
- **Stateless Design**: No server-side session storage
- **Database Connection Pooling**: Efficient connection management
- **Load Balancer Friendly**: Health checks and graceful shutdown

### Performance Optimization
- **Database Indexing**: Optimized query performance
- **Pagination**: Limit result set sizes
- **Caching**: Reduce database load
- **Compression**: Reduce bandwidth usage

### Monitoring Points
- **Health Endpoints**: Application health status
- **Metrics Collection**: Performance metrics
- **Log Aggregation**: Centralized logging
- **Alert Configuration**: Automated alerting

## Deployment Architecture

### Build Process
1. **Dependency Resolution**: `go mod download`
2. **Code Generation**: Swagger documentation
3. **Compilation**: Static binary creation
4. **Testing**: Automated test execution
5. **Packaging**: Container image creation

### Deployment Strategies
- **Blue-Green**: Zero-downtime deployments
- **Rolling**: Gradual instance replacement
- **Canary**: Phased traffic migration
- **Feature Flags**: Runtime feature control

### Environment Configuration
- **Development**: Local development setup
- **Staging**: Production-like testing environment
- **Production**: Live application environment
- **DR**: Disaster recovery environment

## Security Considerations

### Threat Model
1. **Authentication Bypass**: JWT validation, rate limiting
2. **Authorization Escalation**: RBAC, permission validation
3. **Data Injection**: Input sanitization, parameterized queries
4. **Data Exposure**: Access logging, encryption at rest
5. **DoS Attacks**: Rate limiting, request size limits

### Security Controls
- **Input Validation**: All user inputs validated
- **Output Encoding**: XSS prevention
- **Access Control**: Role-based permissions
- **Audit Logging**: All actions logged
- **Encryption**: Sensitive data encrypted

## Future Considerations

### Planned Enhancements
- **Microservices**: Service decomposition
- **Event Sourcing**: Event-driven architecture
- **CQRS**: Command query responsibility segregation
- **GraphQL**: Alternative API interface
- **Real-time**: WebSocket support

### Technology Evolution
- **Database**: PostgreSQL migration path
- **Cache**: Redis integration
- **Messaging**: Event bus implementation
- **Search**: Full-text search capabilities
- **Analytics**: Business intelligence integration