gatehouse-api/docs/architecture.md

# Authy2 Backend - Architecture Documentation

## Overview

This document describes the architecture and design decisions for the Authy2 backend authentication and authorization API.

## Architecture Pattern

The application follows a **layered architecture pattern** with clear separation of concerns:

```
┌─────────────────────────────────────┐
│          API Layer (Routes)         │  Flask blueprints, request validation
├─────────────────────────────────────┤
│       Service Layer (Business)      │  Business logic, orchestration
├─────────────────────────────────────┤
│        Data Layer (Models)          │  ORM models, database access
├─────────────────────────────────────┤
│          Database (PostgreSQL)      │  Data persistence
└─────────────────────────────────────┘
```

### Key Principles

1. **Separation of Concerns**: Each layer has distinct responsibilities
2. **Dependency Injection**: Extensions initialized separately
3. **Factory Pattern**: Application factory for flexible configuration
4. **Repository Pattern**: Service layer abstracts data access
5. **Single Responsibility**: Each module has one reason to change

## Component Structure

### 1. Application Factory (`app/__init__.py`)

Implements the factory pattern for creating Flask applications with different configurations.

**Responsibilities**:
- Initialize Flask app
- Load configuration
- Initialize extensions
- Register blueprints
- Setup middleware
- Register error handlers

### 2. Models Layer (`app/models/`)

SQLAlchemy ORM models representing the database schema.

**Key Models**:
- `User`: User accounts
- `Organization`: Multi-tenant organizations
- `OrganizationMember`: User-organization membership
- `AuthenticationMethod`: Multi-method authentication
- `Session`: User session management
- `AuditLog`: Activity tracking
- `OIDCClient`: OAuth2/OIDC clients

**Base Model Features**:
- UUID primary keys
- Timestamps (created_at, updated_at)
- Soft delete (deleted_at)
- Common methods (save, delete, update, to_dict)

### 3. Service Layer (`app/services/`)

Contains business logic and orchestrates data access.

**Services**:
- `AuthService`: Authentication operations
- `UserService`: User management
- `OrganizationService`: Organization management
- `SessionService`: Session management
- `AuditService`: Audit logging

**Benefits**:
- Keeps controllers thin
- Testable business logic
- Reusable across endpoints
- Transaction management

### 4. API Layer (`app/api/`)

Flask blueprints defining HTTP endpoints.

**Structure**:
- Versioned blueprints (`v1/`, future `v2/`)
- RESTful design
- Request validation with Marshmallow
- Response formatting

**Endpoint Groups**:
- `auth.py`: Authentication endpoints
- `users.py`: User profile endpoints
- `organizations.py`: Organization CRUD

### 5. Schemas (`app/schemas/`)

Marshmallow schemas for validation and serialization.

**Types**:
- Input validation schemas
- Output serialization schemas
- Nested schemas for relationships

### 6. Middleware (`app/middleware/`)

Request/response middleware components.

**Components**:
- `RequestIDMiddleware`: Request tracing
- `SecurityHeadersMiddleware`: Security headers
- `CORS`: Cross-origin resource sharing

### 7. Exceptions (`app/exceptions/`)

Custom exception hierarchy for API errors.

**Hierarchy**:
```
BaseAPIException
├── UnauthorizedError (401)
├── ForbiddenError (403)
├── ValidationError (400)
├── NotFoundError (404)
└── ConflictError (409)
```

### 8. Utilities (`app/utils/`)

Shared utilities and helpers.

**Components**:
- `response.py`: Standardized API responses
- `constants.py`: Enums and constants
- `decorators.py`: Authentication decorators

## Data Models

### User Model

```python
User
├── id: UUID (PK)
├── email: String (unique)
├── email_verified: Boolean
├── full_name: String
├── status: Enum (active, inactive, suspended)
├── last_login_at: DateTime
└── relationships:
    ├── authentication_methods
    ├── sessions
    ├── organization_memberships
    └── audit_logs
```

### Organization Model

```python
Organization
├── id: UUID (PK)
├── name: String
├── slug: String (unique)
├── description: Text
├── is_active: Boolean
├── settings: JSON
└── relationships:
    ├── members (OrganizationMember)
    └── oidc_clients
```

### Authentication Method Model

```python
AuthenticationMethod
├── id: UUID (PK)
├── user_id: UUID (FK)
├── method_type: Enum (password, google, github, oidc)
├── password_hash: String (for password auth)
├── provider_user_id: String (for OAuth)
├── provider_data: JSON
└── is_primary: Boolean
```

## Security Architecture

### Authentication Flow

1. User submits credentials
2. `AuthService.authenticate()` validates credentials
3. Session created with secure token
4. Token stored in Redis
5. Session ID returned to client
6. Subsequent requests authenticated via session

### Authorization Flow

1. Request includes session token
2. `@login_required` decorator validates session
3. User loaded into `g.current_user`
4. `@require_role` checks organization permissions
5. Request proceeds or returns 403

### Password Security

- Bcrypt hashing (12+ rounds in production)
- Configurable rounds per environment
- No plain-text passwords stored
- Password strength validation

### Session Security

- Secure session tokens (32-byte random)
- Configurable expiration
- Session revocation support
- IP and user agent tracking

## API Response Format

All responses follow a standardized envelope:

```json
{
  "version": "1.0",
  "success": boolean,
  "code": number,
  "message": string,
  "request_id": string,
  "data": object | null,
  "error": {
    "type": string,
    "details": object
  } | null,
  "meta": object | null
}
```

**Benefits**:
- Consistent client parsing
- Request tracing
- Error handling
- Pagination metadata

## Database Design

### Multi-Tenancy

Organizations provide multi-tenancy:
- Each org is isolated
- Users can belong to multiple orgs
- Role-based access per org

### Audit Trail

Comprehensive logging:
- All mutations logged
- User context captured
- IP and user agent tracked
- Queryable history

### Soft Deletes

All models support soft delete:
- `deleted_at` timestamp
- Allows recovery
- Maintains referential integrity
- Audit trail preserved

## Configuration Management

### Environment-based Config

```
config/
├── base.py           # Common settings
├── development.py    # Dev overrides
├── testing.py        # Test config
└── production.py     # Production settings
```

### Configuration Hierarchy

1. Base configuration
2. Environment-specific overrides
3. Environment variables (highest priority)

## Testing Strategy

### Unit Tests

- Test individual functions/methods
- Mock external dependencies
- Fast execution
- High coverage target (>80%)

### Integration Tests

- Test API endpoints end-to-end
- Use test database
- Verify request/response flow
- Authentication flow testing

### Test Fixtures

- Reusable test data
- Database setup/teardown
- Authenticated clients
- Sample users/organizations

## Deployment Architecture

### Recommended Setup

```
┌─────────────┐
│  Load       │
│  Balancer   │
└──────┬──────┘
       │
   ┌───┴────┐
   │        │
┌──▼──┐  ┌──▼──┐
│ Web  │  │ Web  │  Gunicorn workers
│ App  │  │ App  │
└──┬───┘  └──┬───┘
   │         │
   └────┬────┘
        │
    ┌───▼────┐
    │ Redis  │  Session storage
    └────────┘
        │
    ┌───▼────────┐
    │ PostgreSQL │  Data persistence
    └────────────┘
```

### Scaling Considerations

- Stateless application (sessions in Redis)
- Horizontal scaling via load balancer
- Database connection pooling
- Redis for distributed sessions
- Celery for background tasks (future)

## Error Handling

### Exception Hierarchy

All exceptions inherit from `BaseAPIException`:
- Consistent error responses
- HTTP status codes
- Error type categorization
- Detailed error information

### Global Error Handlers

- Catch all exceptions
- Log errors appropriately
- Return standardized responses
- Never expose internals

## Logging & Monitoring

### Audit Logging

- User actions tracked
- Organization changes logged
- Authentication events
- Queryable audit trail

### Application Logging

- Structured logging
- Request/response logging
- Error logging
- Performance metrics

## Future Enhancements

1. **OAuth Provider**: Implement full OAuth2/OIDC provider
2. **MFA**: Multi-factor authentication
3. **Email Service**: Email verification and notifications
4. **Webhooks**: Event-driven notifications
5. **API Keys**: Service account authentication
6. **Rate Limiting**: Per-user/org rate limits
7. **Background Jobs**: Celery integration
8. **Monitoring**: Prometheus/Grafana metrics

## Best Practices

1. **Always use service layer** for business logic
2. **Validate all inputs** with Marshmallow schemas
3. **Use decorators** for authentication/authorization
4. **Log important events** to audit log
5. **Follow RESTful conventions** for endpoints
6. **Write tests** for all new features
7. **Use transactions** for multi-step operations
8. **Never return sensitive data** without filtering
9. **Keep controllers thin** - logic goes in services
10. **Version the API** for backward compatibility