# crowcpp/crow architecture

> Architecture diagram of the GitHub repository crowcpp/crow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/crowcpp/crow
- Repository: https://github.com/crowcpp/crow

## Overview

##### Project Type & Purpose
- Crow is a header-only C++ microframework for building HTTP and Websocket applications.
- It aims to provide easy routing (similar to Flask), built-in JSON support, middleware extensibility, and fast performance.
- It also supports templating (via Mustache), static file serving, and multipart handling.

##### Key Components & Their Locations
- Application Core:
– The central “crow::SimpleApp” and related classes that initialize and run the web server.
– Found in headers like include/crow/app.h.
- Routing Engine:
– Implemented in include/crow/routing.h and associated files to interpret URLs and map them to handlers.
- HTTP Server & Connection Management:
– Located in include/crow/http_server.h, include/crow/http_connection.h, and include/crow/http_request.h/response.h.
– Uses http-parser (from the incorporated source in the project’s attributions) for parsing HTTP messages.
- Middleware Support:
– Facilitates extensions and pre-/post-processing of requests.
– Look at include/crow/middleware.h and the subdirectory include/crow/middlewares (for cookie, cors, session handling, etc.).
- JSON Handling:
– Provided in include/crow/json.h, enabling the creation and manipulation of JSON responses.
- Templating:
– The mustache based templating engine is included for dynamic HTML generation; see include/crow/mustache.h.
- Websocket Support:
– Look into include/crow/websocket.h as well as examples in the examples/websocket folder.
- Additional Utilities and Helpers:
– Compression (include/crow/compression.h), multipart parsing (include/crow/multipart.h & multipart_view.h), query string handling, and logging (include/crow/logging.h).
- Build, Tests, and Documentation:
– Build system: CMakeLists.txt and several cmake configuration files.
– Tests: Organized in tests/ (including fuzzing, unit tests, and integration tests).
– Documentation and examples are provided under docs/ and examples/ respectively.

##### Relationships & Data Flow
- The HTTP Server (crow::http_server) uses http-parser to convert raw HTTP input into structured requests.
- The Routing module then directs this request to the corresponding application handler defined in user code (using macros like CROW_ROUTE).
- Before reaching the handler, Middleware (if any) intercepts the request for authentication, logging, or other cross-cutting concerns.
- The handler processes the request—possibly interacting with the JSON or templating modules—and generates a response.
- For Websocket endpoints, the connection is managed by the Websocket component.
- The response flows back through any middleware (post-processing) and is then sent out over the HTTP connection.

##### Architectural Patterns
- Layered Architecture:
– Clear separation between request routing, middleware processing, and response generation.
- Component-based Design:
– Each module (routing, middleware, websocket, templating) is implemented in its own set of header files, promoting modularity.
- Use of External Libraries:
– Integrates external open-source modules (like http-parser, qs_parse, TinySHA1) that are key to parsing, query processing, and handshake operations, respectively.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["External HTTP Request"]:::external

    subgraph "HTTP Layer"
        B["HTTP Server"]:::network
        C["HTTP Request"]:::network
        D["HTTP Connection"]:::network
        E["HTTP Response"]:::network
    end

    subgraph "Core Processing"
        F["Routing Engine"]:::core
        G["Middleware Support"]:::core
        H["Application Core"]:::core
        J["JSON Handling"]:::core
        K["Templating Module"]:::core
        I["Websocket Support"]:::core
        I2["Websocket Example"]:::core
    end

    L["Utility Components (Compression, Multipart, Logging)"]:::utility
    M["External Libraries (http-parser, qs_parse, TinySHA1, Catch2)"]:::utility
    N["Build, Tests, & Docs"]:::dev

    %% Connections for HTTP Layer
    A -->|"sends"| B
    B -->|"parses"| C
    B -.->|"manages"| D
    C -->|"forwards to"| F

    %% Core Processing flow
    F -->|"routes"| G
    G -->|"calls"| H
    H -->|"generates"| E

    %% Side branches from Core
    H -->|"uses"| J
    H -->|"renders with"| K
    F -->|"handles WS"| I
    I -->|"example"| I2
    I -->|"responds"| E

    %% Utility integration
    L -->|"assists"| H
    M -->|"supports"| B
    M -->|"aids"| F
    N -->|"builds/tests"| H

    %% Click Events
    click B "https://github.com/crowcpp/crow/blob/master/include/crow/http_server.h"
    click C "https://github.com/crowcpp/crow/blob/master/include/crow/http_request.h"
    click D "https://github.com/crowcpp/crow/blob/master/include/crow/http_connection.h"
    click E "https://github.com/crowcpp/crow/blob/master/include/crow/http_response.h"
    click F "https://github.com/crowcpp/crow/blob/master/include/crow/routing.h"
    click G "https://github.com/crowcpp/crow/blob/master/include/crow/middleware.h"
    click H "https://github.com/crowcpp/crow/blob/master/include/crow/app.h"
    click I "https://github.com/crowcpp/crow/blob/master/include/crow/websocket.h"
    click I2 "https://github.com/crowcpp/crow/blob/master/examples/websocket/example_ws.cpp"
    click J "https://github.com/crowcpp/crow/blob/master/include/crow/json.h"
    click K "https://github.com/crowcpp/crow/blob/master/include/crow/mustache.h"
    click L "https://github.com/crowcpp/crow/blob/master/include/crow/compression.h"
    click N "https://github.com/crowcpp/crow/blob/master/CMakeLists.txt"

    %% Styles
    classDef external fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef network fill:#A9DFBF,stroke:#145A32,stroke-width:2px;
    classDef core fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef utility fill:#F5CBA7,stroke:#9C640C,stroke-width:2px;
    classDef dev fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;
```
