# wxn0brp/falconframe architecture

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

- Interactive diagram: https://gitdiagram.com/wxn0brp/falconframe
- Repository: https://github.com/wxn0brp/falconframe

## Overview

##### Project type and purpose
- FalconFrame is a lightweight, middleware-first TypeScript web framework inspired by Express.
- It provides routing, static file serving, request validation, cookie management, and logging with zero external dependencies (apart from a logger).

##### File structure
- Top-level files:
- package.json, tsconfig.json, sugilite.json – build and config files
- README.md – project description
- .github/workflows/build.yml – CI build
- public/ – static assets (index.html, style.css)
- src/ – core framework code:
- index.ts – framework entry point (FalconFrame class, app.listen)
- helpers.ts, req.ts, res.ts, valid.ts – middleware, request/response abstractions, validation
- types.ts – TypeScript interfaces/types
- test.ts – example/test harness

##### Key insights from README
- Middleware chaining model, zero-dependency routing engine
- Inline schemas for validation
- Cookie management and static serving APIs

##### Main components
a. HTTP Server (Node.js HTTP module)
b. Request Parser & Logger Middleware
c. Router Engine (routes table, HTTP methods)
d. Middleware Chain Manager
- Built-in middlewares: static file handler, validation, cookies
- User-defined middlewares (app.use, route-specific)
e. Handler Functions (controller logic)
f. Response Builder (res.json, res.redirect, res.cookie)
g. Static File Service (serves files from public/)
h. Validation Engine (valid.ts)
i. Cookie Manager (req.cookies, res.cookie)

##### Relationships and interactions
- Incoming HTTP request → Node.js HTTP server
- Server passes raw request to FalconFrame core →
1. Invoke global middleware (logger)
2. Router matches path + method → invokes route-specific middleware chain
3. Middleware functions call next() or short-circuit with response
4. Validation middleware uses inline schemas to annotate req.validErrors
5. Cookie middleware reads/writes cookies
6. Handler returns data or writes to res object
- Response Builder sends HTTP response back to client

##### Architectural patterns and principles
- Middleware pipeline (chain of responsibility)
- Router as dispatcher (similar to Express)
- Separation of concerns: parsing, routing, validation, cookies, static serving
- Zero external dependencies – all functionality is in pure TypeScript modules

##### Technologies and frameworks
- Language: TypeScript
- Runtime: Node.js HTTP module
- Build/packaging: package.json, tsconfig.json, sugilite.json, GitHub Actions CI

##### Elements
- Clear component names: HTTP Server, Router, Middleware Chain, Validator, Cookie Manager, Static File Service, Response Builder
- HTTP client → HTTP Server → FalconFrame Core
- Middleware flow → Handler → Response Builder → HTTP client
- Distinguish framework internals vs. user-provided handlers vs. file system

##### Final advice
- Be very detailed: break out each middleware type as separate components
- Request/response lifecycle end to end
- Extension points (app.use, app.get/post, static) to show how a user plugs into the framework
- Don’t overcomplicate—focus on core pipeline and major modules

## Diagram (Mermaid)

```mermaid
flowchart TB
    HTTPClient["HTTP Client"]:::external
    HTTPServer["HTTP Server"]:::external
    RequestParserLogger["Request Parser & Logger Middleware"]:::internal
    RouterEngine["Router Engine"]:::internal
    MiddlewareManager["Middleware Chain Manager"]:::internal
    subgraph "Middleware Chain"
        direction TB
        Logger["1. Logger"]:::internal
        StaticHandler["2. Static File Handler"]:::static
        ValidationEngine["3. Validation Engine"]:::internal
        CookieManager["4. Cookie Manager"]:::internal
        UserMiddleware["5. User-defined Middleware"]:::internal
    end
    HandlerFunctions["Handler Functions"]:::user
    ResponseBuilder["Response Builder"]:::internal
    PublicDir["public/ (Static Assets)"]:::static
    TypeDefinitions["Type Definitions"]:::type
    TestHarness["Example/Test Harness"]:::user

    HTTPClient -->|"HTTP Request"| HTTPServer
    HTTPServer -->|"initialize FalconFrame"| RequestParserLogger
    RequestParserLogger -->|"parse & log"| RouterEngine
    RouterEngine -->|"dispatch"| MiddlewareManager
    MiddlewareManager --> Logger
    Logger --> StaticHandler
    StaticHandler --> ValidationEngine
    ValidationEngine --> CookieManager
    CookieManager --> UserMiddleware
    UserMiddleware --> HandlerFunctions
    HandlerFunctions --> ResponseBuilder
    ResponseBuilder -->|"HTTP Response"| HTTPClient

    PublicDir -.-> StaticHandler

    TypeDefinitions --> RequestParserLogger
    TypeDefinitions --> RouterEngine
    TypeDefinitions -.-> ValidationEngine
    TypeDefinitions -.-> CookieManager
    TypeDefinitions -.-> ResponseBuilder

    TestHarness --> RouterEngine
    HTTPServer --> TestHarness

    click HTTPServer "https://github.com/wxn0brp/falconframe/blob/master/src/index.ts"
    click RouterEngine "https://github.com/wxn0brp/falconframe/blob/master/src/index.ts"
    click MiddlewareManager "https://github.com/wxn0brp/falconframe/blob/master/src/helpers.ts"
    click RequestParserLogger "https://github.com/wxn0brp/falconframe/blob/master/src/helpers.ts"
    click StaticHandler "https://github.com/wxn0brp/falconframe/blob/master/src/helpers.ts"
    click ValidationEngine "https://github.com/wxn0brp/falconframe/blob/master/src/valid.ts"
    click CookieManager "https://github.com/wxn0brp/falconframe/blob/master/src/req.ts"
    click ResponseBuilder "https://github.com/wxn0brp/falconframe/blob/master/src/res.ts"
    click PublicDir "https://github.com/wxn0brp/falconframe/tree/master/public/"
    click TypeDefinitions "https://github.com/wxn0brp/falconframe/blob/master/src/types.ts"
    click TestHarness "https://github.com/wxn0brp/falconframe/blob/master/src/test.ts"

    classDef external fill:#ADD8E6,stroke:#000;
    classDef internal fill:#90EE90,stroke:#000;
    classDef static fill:#FFD700,stroke:#000;
    classDef type fill:#D3D3D3,stroke:#000;
    classDef user fill:#FFB6C1,stroke:#000;
```
