Skip to content

architecture.md

Latest commit

 

History

History
349 lines (287 loc) · 14.1 KB

architecture.md

File metadata and controls

349 lines (287 loc) · 14.1 KB

Document Analyzer Operator - Architecture

System Overview

The Document Analyzer Operator Platform is a multi-agent system for document analysis, validation, and processing. It provides a scalable architecture for orchestrating AI agents, managing workflows, and maintaining knowledge bases.

Architecture Diagram

┌─────────────────────────────────────────────────────────────────┐
│                         Client Layer                             │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────────────┐  │
│  │   Web    │  │  Mobile  │  │   CLI    │  │  Third-Party   │  │
│  │   App    │  │   App    │  │   Tool   │  │  Integrations  │  │
│  └──────────┘  └──────────┘  └──────────┘  └────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      API Gateway Layer                           │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │              FastAPI Backend (Port 8000)                   │ │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐    │ │
│  │  │   Auth      │  │   Agents    │  │    Workflows    │    │ │
│  │  │   API       │  │   API       │  │    API          │    │ │
│  │  └─────────────┘  └─────────────┘  └─────────────────┘    │ │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐    │ │
│  │  │   Tasks     │  │  Knowledge  │  │   Validation    │    │ │
│  │  │   API       │  │   Base API  │  │   API           │    │ │
│  │  └─────────────┘  └─────────────┘  └─────────────────┘    │ │
│  └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Service Layer                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │   User      │  │   Agent     │  │    Workflow             │  │
│  │   Service   │  │   Service   │  │    Orchestrator         │  │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │   Task      │  │  Knowledge  │  │    Validation           │  │
│  │   Service   │  │   Service   │  │    Engine               │  │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Data Layer                                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │  PostgreSQL │  │    Redis    │  │      MinIO/S3           │  │
│  │  (Primary)  │  │   (Cache)   │  │    (Object Store)       │  │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Core Components

1. API Layer (app/api/)

Responsibilities:

  • HTTP request handling
  • Authentication and authorization
  • Request validation
  • Response serialization

Structure:

api/
├── v1/
│   ├── routes/
│   │   ├── auth.py        # Authentication endpoints
│   │   ├── agents.py      # Agent CRUD operations
│   │   ├── workflows.py   # Workflow management
│   │   ├── tasks.py       # Task operations
│   │   ├── knowledge.py   # Knowledge base operations
│   │   └── validation.py  # Validation operations
│   └── router.py          # API router configuration
└── deps.py                # Dependencies (auth, DB, etc.)

2. Core Layer (app/core/)

Responsibilities:

  • Application configuration
  • Security utilities
  • Logging configuration

Key Files:

  • settings.py: Pydantic-based configuration management
  • security.py: JWT, password hashing, token management
  • logging_config.py: Logging setup

3. Database Layer (app/db/, app/models/)

Responsibilities:

  • Database connection management
  • ORM models
  • Migrations

Models:

  • User: User accounts and authentication
  • Agent: AI agent instances
  • AgentType: Agent type definitions
  • Workflow: Multi-agent workflows
  • Task: Individual work items
  • Workspace: Project organization
  • KnowledgeEntity: Knowledge base content
  • ValidationResult: Validation outcomes

4. Service Layer (app/services/)

Responsibilities:

  • Business logic
  • Transaction management
  • Cross-cutting concerns

Services:

  • UserService: User management
  • AgentService: Agent lifecycle
  • WorkflowService: Workflow orchestration
  • TaskService: Task management
  • KnowledgeService: Knowledge base operations
  • ValidationService: Validation engine

5. WebSocket Layer (app/websocket/)

Responsibilities:

  • Real-time event streaming
  • Connection management
  • Event subscription system

Components:

  • manager.py: WebSocket connection manager
  • events.py: Event types and pub-sub system

Data Flow

Authentication Flow

Client → POST /api/v1/auth/login
         ↓
     Validate credentials
         ↓
     Generate JWT tokens
         ↓
     Return tokens + user data
         ↓
Client stores tokens
         ↓
Client includes token in Authorization header
         ↓
API validates token on each request

Agent Creation Flow

Client → POST /api/v1/agents
         ↓
     Authenticate user
         ↓
     Validate request data
         ↓
     Create Agent record
         ↓
     Initialize agent resources
         ↓
     Return agent data

Workflow Execution Flow

Client → POST /api/v1/workflows/{id}/execute
         ↓
     Validate workflow definition
         ↓
     Create task graph
         ↓
     Queue tasks for execution
         ↓
     Agents process tasks
         ↓
     Stream progress via WebSocket
         ↓
     Store results
         ↓
     Notify client on completion

Security Architecture

Authentication

  • JWT Tokens: Short-lived access tokens (30 min) + long-lived refresh tokens (7 days)
  • Token Blacklist: Redis-based token revocation
  • Password Hashing: bcrypt with configurable rounds
  • Rate Limiting: Request throttling per user/IP

Authorization

  • RBAC: Role-based access control (user, admin, superadmin)
  • Resource Ownership: Users can only access their own resources
  • API Key Support: Optional API key authentication for service accounts

Data Protection

  • Input Validation: Pydantic schemas for all inputs
  • SQL Injection Prevention: SQLAlchemy ORM with parameterized queries
  • XSS Prevention: Security headers, output encoding
  • CORS: Configurable cross-origin resource sharing

Database Schema

Entity Relationships

User (1) ────── (M) Agent
User (1) ────── (M) Workflow
User (1) ────── (M) Workspace
Workspace (1) ── (M) KnowledgeEntity
Agent (1) ────── (M) Task
Workflow (1) ─── (M) Task
Task (1) ─────── (M) Task (subtasks)
Task (1) ─────── (M) ValidationResult
AgentType (1) ── (M) Agent

Scalability Considerations

Horizontal Scaling

  • Stateless API: No session state in API servers
  • Redis Session Store: Centralized session management
  • Database Connection Pooling: Efficient connection reuse
  • Load Balancer Ready: Multiple API instances behind LB

Performance Optimization

  • Async/Await: Non-blocking I/O operations
  • Database Indexing: Optimized queries
  • Caching: Redis for frequently accessed data
  • Pagination: Limit response sizes

High Availability

  • Health Checks: /api/v1/health, /api/v1/ready, /api/v1/live
  • Graceful Shutdown: Proper connection cleanup
  • Retry Logic: Exponential backoff for transient failures
  • Circuit Breaker: Prevent cascade failures

Deployment Architecture

Development

┌─────────────┐
│   Docker    │
│  Compose    │
│             │
│ ┌─────────┐ │
│ │ FastAPI │ │
│ └─────────┘ │
│ ┌─────────┐ │
│ │PostgreSQL││
│ └─────────┘ │
│ ┌─────────┐ │
│ │  Redis  │ │
│ └─────────┘ │
│ ┌─────────┐ │
│ │  MinIO  │ │
│ └─────────┘ │
└─────────────┘

Production

┌─────────────────────────────────────────┐
│          Load Balancer                  │
└─────────────────────────────────────────┘
              │         │
              ▼         ▼
    ┌─────────────┐ ┌─────────────┐
    │  FastAPI 1  │ │  FastAPI 2  │
    └─────────────┘ └─────────────┘
              │         │
              └────┬────┘
                   │
         ┌─────────┼─────────┐
         ▼         ▼         ▼
   ┌──────────┐ ┌──────┐ ┌────────┐
   │PostgreSQL│ │Redis │ │ MinIO  │
   │ Cluster  │ │Cluster│ │ or S3  │
   └──────────┘ └──────┘ └────────┘

Technology Stack

Component Technology Purpose
Framework FastAPI Web API
Language Python 3.11+ Backend logic
Database PostgreSQL 16 Primary data store
Cache Redis 7 Caching, sessions
ORM SQLAlchemy 2.0 Database operations
Validation Pydantic 2 Data validation
Auth JWT (PyJWT) Token-based auth
Password bcrypt Password hashing
Storage MinIO/S3 Object storage
Container Docker Containerization
Migration Alembic DB migrations

API Versioning

  • URL Versioning: /api/v1/, /api/v2/, etc.
  • Backward Compatibility: Maintain compatibility within major versions
  • Deprecation Policy: 6-month notice for breaking changes

Monitoring and Observability

Logging

  • Structured JSON logging
  • Correlation IDs for request tracing
  • Log levels: DEBUG, INFO, WARNING, ERROR, CRITICAL

Metrics (Future)

  • Request latency
  • Error rates
  • Database query performance
  • Cache hit rates

Tracing (Future)

  • Distributed tracing with OpenTelemetry
  • Request flow visualization
  • Performance bottleneck identification

Future Enhancements

  1. Message Queue: Celery/RabbitMQ for background tasks
  2. GraphQL API: Alternative query interface
  3. Vector Database: Specialized storage for embeddings
  4. Service Mesh: Istio for advanced traffic management
  5. API Gateway: Kong/Tyk for advanced API management