# poem-web/poem architecture

> Architecture diagram of the GitHub repository poem-web/poem, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/poem-web/poem
- Repository: https://github.com/poem-web/poem

## Overview

##### Main Components Overview

a) Core Framework (poem)
- Subsystems:
- HTTP Server/Listener Layer
- Routing System
- Middleware Pipeline
- Request/Response Handlers
- WebSocket Support
- Session Management
- Static File Handling

b) OpenAPI Integration (poem-openapi)
- As a side component
- Include:
- API Documentation Generator
- Schema Validation
- Request/Response Validation
- Security Schemes
- UI Components (Swagger, Redoc, RapiDoc)

c) AWS Lambda Integration (poem-lambda)
- As another side component
- Integration with AWS Lambda runtime

##### Key Architectural Elements

Frontend Layer:
- HTTP/HTTPS Listeners
- WebSocket Handlers
- Static File Servers
- SSE (Server-Sent Events)

Middleware Layer:
- Authentication
- CORS
- Compression
- Logging/Tracing
- Session Management
- Error Handling

Core Processing Layer:
- Router
- Endpoint Handlers
- Request Processing
- Response Formation

Integration Layer:
- OpenAPI Integration
- AWS Lambda Support
- External Service Connectors

##### Additional Elements

- Security features (TLS, CSRF, etc.)
- Monitoring capabilities (OpenTelemetry, Prometheus)
- Database integrations
- Caching mechanisms
- File handling systems

##### Implementation Details

- Request flow through the system
- Error handling paths
- Middleware chain execution
- Plugin/Extension points
- Configuration options

##### Deployment Options

Separate sections for:
- Standard HTTP/HTTPS deployment
- AWS Lambda deployment
- Unix socket deployment

##### Notes Section

Notes about:
- Scalability options
- Security considerations
- Performance characteristics
- Extension points

Remember to emphasize the framework's key features:
- Full-featured web capabilities
- Easy-to-use API design
- OpenAPI integration
- AWS Lambda support
- Extensive middleware support
- Security features

This system design should help developers understand both the high-level architecture and the detailed interactions between components, while maintaining clarity and usefulness for implementation and maintenance purposes.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Core["Core Framework (poem)"]
        HTTP["HTTP Server/Listener"]:::core
        Router["Routing System"]:::core
        Middleware["Middleware Pipeline"]:::core
        ReqRes["Request/Response Handlers"]:::core
        WebSocket["WebSocket Support"]:::core
        Session["Session Management"]:::core
        StaticFiles["Static File Handling"]:::core
        ErrorHandler["Error Handling"]:::core
        Endpoint["Endpoint Handling"]:::core
        WebUtils["Web Utilities"]:::core

        subgraph Security["Security Layer"]
            CORS["CORS"]:::security
            CSRF["CSRF Protection"]:::security
            TLS["TLS Support"]:::security
        end

        HTTP --> Router
        Router --> Middleware
        Middleware --> ReqRes
        ReqRes --> Endpoint
        Endpoint --> WebUtils
        WebSocket --> WebUtils
        Session --> Middleware
        StaticFiles --> Endpoint
        ErrorHandler --> ReqRes
        Security --> Middleware
    end

    subgraph OpenAPI["OpenAPI Integration"]
        APIMain["OpenAPI Main"]:::openapi
        SchemaVal["Schema Validation"]:::openapi
        SecSchemes["Security Schemes"]:::openapi
        
        subgraph UI["UI Components"]
            SwaggerUI["Swagger UI"]:::ui
            RapiDoc["RapiDoc"]:::ui
            ReDoc["ReDoc"]:::ui
        end

        APIMain --> SchemaVal
        APIMain --> SecSchemes
        APIMain --> UI
    end

    subgraph Lambda["AWS Lambda Integration"]
        LambdaRuntime["Lambda Runtime"]:::lambda
    end

    Core --> OpenAPI
    Core --> Lambda

    %% Click events for component mapping
    click HTTP "https://github.com/poem-web/poem/blob/master/poem/src/listener/mod.rs"
    click Router "https://github.com/poem-web/poem/blob/master/poem/src/route/mod.rs"
    click Middleware "https://github.com/poem-web/poem/blob/master/poem/src/middleware/mod.rs"
    click WebSocket "https://github.com/poem-web/poem/blob/master/poem/src/web/websocket/mod.rs"
    click Session "https://github.com/poem-web/poem/blob/master/poem/src/session/mod.rs"
    click StaticFiles "https://github.com/poem-web/poem/blob/master/poem/src/endpoint/static_files.rs"
    click ReqRes "https://github.com/poem-web/poem/blob/master/poem/src/request.rs"
    click ErrorHandler "https://github.com/poem-web/poem/blob/master/poem/src/error.rs"
    click Endpoint "https://github.com/poem-web/poem/blob/master/poem/src/endpoint/mod.rs"
    click WebUtils "https://github.com/poem-web/poem/blob/master/poem/src/web/mod.rs"
    click CORS "https://github.com/poem-web/poem/blob/master/poem/src/middleware/cors.rs"
    click CSRF "https://github.com/poem-web/poem/blob/master/poem/src/middleware/csrf.rs"
    click TLS "https://github.com/poem-web/poem/blob/master/poem/src/listener/tls.rs"
    click APIMain "https://github.com/poem-web/poem/blob/master/poem-openapi/src/lib.rs"
    click SchemaVal "https://github.com/poem-web/poem/blob/master/poem-openapi/src/validation/mod.rs"
    click SecSchemes "https://github.com/poem-web/poem/blob/master/poem-openapi/src/auth/mod.rs"
    click SwaggerUI "https://github.com/poem-web/poem/blob/master/poem-openapi/src/ui/swagger_ui/mod.rs"
    click RapiDoc "https://github.com/poem-web/poem/blob/master/poem-openapi/src/ui/rapidoc/mod.rs"
    click ReDoc "https://github.com/poem-web/poem/blob/master/poem-openapi/src/ui/redoc/mod.rs"
    click LambdaRuntime "https://github.com/poem-web/poem/blob/master/poem-lambda/src/lib.rs"

    %% Styling
    classDef core fill:#2374ab
    classDef security fill:#2a9d8f
    classDef openapi fill:#e9c46a
    classDef lambda fill:#f4a261
    classDef ui fill:#e76f51

    %% Legend
    subgraph Legend
        L1["Core Components"]:::core
        L2["Security Features"]:::security
        L3["OpenAPI Components"]:::openapi
        L4["Lambda Integration"]:::lambda
        L5["UI Components"]:::ui
    end
```
