high‐level‐architecture

High-Level Architecture

This diagram shows the overall system architecture following Clean Architecture principles.

graph TB
    subgraph "PJS Ecosystem"
        subgraph "Client Side"
            JSClient[PJS JS Client<br/>TypeScript/JavaScript]
            RustClient[PJS Rust Client<br/>Future Implementation]
        end
        
        subgraph "Server Side - Clean Architecture"
            subgraph "Infrastructure Layer"
                HTTP[HTTP Transport<br/>Axum/Hyper]
                WS[WebSocket<br/>tokio-tungstenite]
                Metrics[Metrics<br/>Prometheus]
                Repos[Memory Repository<br/>Future: DB]
            end
            
            subgraph "Application Layer"
                Commands[Commands<br/>CQRS Pattern]
                Queries[Queries<br/>Read Models]
                Services[Application Services<br/>Orchestration]
                DTOs[Data Transfer Objects<br/>API Contract]
            end
            
            subgraph "Domain Layer"
                Aggregates[Stream Session<br/>Aggregate Root]
                Entities[Stream, Frame<br/>Entity Objects]
                ValueObjects[Priority, SessionId<br/>JsonPath, StreamId]
                DomainServices[Priority Service<br/>Domain Logic]
                Events[Domain Events<br/>Event Sourcing]
            end
            
            subgraph "Core Processing"
                Parser[JSON Parser<br/>SIMD + sonic-rs]
                Semantic[Semantic Analysis<br/>Type Detection]
                Compression[Compression<br/>Schema-aware]
                Streaming[Priority Streaming<br/>Frame Generation]
            end
        end
        
        subgraph "Benchmarking & Demo"
            Bench[pjs-bench<br/>Performance Tests]
            Demo[pjs-demo<br/>Examples & Demos]
        end
    end
    
    %% Dependencies flow (Clean Architecture)
    Infrastructure -.-> Application
    Application -.-> Domain
    JSClient <--> HTTP
    JSClient <--> WS
    HTTP --> Services
    WS --> Services
    Services --> Aggregates
    Parser --> Streaming
    Semantic --> Parser
    Compression --> Streaming
    
    %% External dependencies
    Parser -.-> sonic[sonic-rs<br/>SIMD JSON]
    Compression -.-> brotli[Compression libs]
    HTTP -.-> axum[Axum Framework]
    WS -.-> tokio[Tokio Runtime]
    
    classDef domainLayer fill:#e1f5fe
    classDef applicationLayer fill:#f3e5f5
    classDef infrastructureLayer fill:#e8f5e8
    classDef clientLayer fill:#fff3e0
    classDef processingLayer fill:#fce4ec
    
    class Aggregates,Entities,ValueObjects,DomainServices,Events domainLayer
    class Commands,Queries,Services,DTOs applicationLayer
    class HTTP,WS,Metrics,Repos infrastructureLayer
    class JSClient,RustClient clientLayer
    class Parser,Semantic,Compression,Streaming processingLayer

Loading

Layer Responsibilities

Infrastructure Layer (Outer)

• HTTP Transport: Axum-based REST API and streaming endpoints
• WebSocket: Real-time bidirectional communication
• Repositories: Data persistence (currently in-memory)
• Metrics: Performance monitoring and observability

Application Layer (Middle)

• Commands: Write operations following CQRS pattern
• Queries: Read operations with optimized models
• Services: Use case orchestration and business workflows
• DTOs: API contract objects for client communication

Domain Layer (Core)

• Aggregates: StreamSession as the primary aggregate root
• Entities: Stream and Frame with identity and lifecycle
• Value Objects: Priority, JsonPath, SessionId with immutable semantics
• Domain Services: Complex business logic like priority calculation
• Events: Domain events for decoupled communication

Key Design Principles

1. Dependency Inversion: All dependencies point inward toward the domain
2. Separation of Concerns: Each layer has distinct responsibilities
3. High Cohesion: Related functionality grouped together
4. Loose Coupling: Layers communicate through abstractions
5. Single Responsibility: Each component has one reason to change

Performance Optimizations

• SIMD Processing: Vectorized JSON parsing for 2-5x speedup
• Zero-copy Operations: Minimize memory allocations
• Priority Streaming: Deliver critical data first
• Schema-aware Compression: Intelligent data reduction