# engwan/qcgi architecture

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

- Interactive diagram: https://gitdiagram.com/engwan/qcgi
- Repository: https://github.com/engwan/qcgi

## Overview

##### Project Type and Purpose
- This is a full‐stack, server‐side web preprocessor written in C++. Its role is to parse qCGI tags in incoming HTTP requests (via FastCGI), interpret them by offloading logic to an SQL server, manage session state in SQLite, and produce HTML output.
- It’s a proof‐of‐concept toy implementation intended for educational purposes.

##### File Structure Analysis
- Top level:
- README.md – project description, dependencies, syntax overview
- qcgi+ – (presumably the build/install script or executable placeholder)
- src/ – all C++ source code
- test.v – sample qCGI template demonstrating syntax
- src/:
- Makefile – build instructions linking against MySQL, SQLite3, FastCGI, RudeCGI, Boost.Regex
- qcgi+.cpp – main entrypoint, FastCGI loop, integration with RudeCGI
- parser.{cpp,h} – tokenization and parsing of `{.`…`}` tags (uses Boost.Regex)
- interpreter.{cpp,h} – AST walker, translates parsed nodes into SQL queries and HTML fragments
- db.{cpp,h} – MySQL client wrapper for running logic queries
- sessions.{cpp,h} – SQLite wrapper to store session data
- utils.{cpp,h} – helper functions for escaping, string manipulation, etc.

##### Key Architectural Patterns
- Modular layering inside one process: separation of concern between parsing, interpretation, database I/O, session management, and request handling.
- Single FastCGI worker process model: persistent process handles multiple requests.
- Interpreter pattern (AST + visitation) for implementing qCGI logic constructs.
- Adapter/wrapper pattern for DB clients (MySQL and SQLite).

##### Main Components
a. External Actors
- Web Client (browser)
- Web Server (e.g., Apache/nginx + fcgid or mod_fcgid)
b. Core System (FastCGI App)
1. FastCGI Listener (qcgi+.cpp + RudeCGI)
2. Parser Module (parser.cpp/h + Boost.Regex)
3. Interpreter Module (interpreter.cpp/h)
4. Database Layer
– MySQL Client (db.cpp/h) for business logic & flow control
– SQLite Client (sessions.cpp/h) for session persistence
5. Utilities (utils.cpp/h)
c. Supporting Artifacts
- qCGI Template Files (e.g., test.v)
- Build System (Makefile, gcc, linking libraries)

##### Component Interactions
- HTTP Request from Web Client → Web Server → FastCGI Listener
- FastCGI Listener uses RudeCGI to parse HTTP headers & body
- Template content scanned by Parser → emits AST or intermediate tokens
- Interpreter consumes AST, issues SQL queries via MySQL client to implement logic (if/else, loops)
- Interpreter reads/writes session state via SQLite client
- Interpreter emits dynamic HTML output → FastCGI Listener returns HTTP Response
- Build interactions: Makefile links correct libraries; hardcoded config parameters in db.cpp/h

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External actors
    WebClient["Web Client (Browser)"]:::external
    WebServer["Web Server (Apache/nginx + FCGI)"]:::external

    %% Core Application
    subgraph "qCGI FastCGI Application"
        direction TB
        FastCGIListener["FastCGI Listener\n(qcgi+.cpp + RudeCGI)"]:::internal
        Parser["Parser Module\n(parser.cpp/h + Boost.Regex)"]:::internal
        Interpreter["Interpreter Module\n(interpreter.cpp/h)"]:::internal
        subgraph "Database Layer"
            direction TB
            MySQLClient["MySQL Client Wrapper\n(db.cpp/h)"]:::internal
            SQLiteClient["SQLite Session Store\n(sessions.cpp/h)"]:::internal
        end
        Utils["Utilities\n(utils.cpp/h)"]:::internal
    end

    %% Datastores
    MySQLServer["MySQL Server"]:::datastore
    SQLiteDB["SQLite DB File"]:::datastore

    %% Filesystem / Templates / Build
    TestTemplate["qCGI Template File\n(test.v)"]:::file
    README["Project Description\n(README.md)"]:::file
    Makefile["Build System\n(src/Makefile)"]:::file
    Executable["qCGI Executable Placeholder\n(qcgi+)"]:::file

    %% Flows
    WebClient -->|"HTTP Request"| WebServer
    WebServer -->|"FCGI Request"| FastCGIListener
    FastCGIListener -->|"parse HTTP headers & body"| Parser
    Parser -->|"emit AST"| Interpreter
    Interpreter -->|"execute logic"| MySQLClient
    MySQLClient -->|"SQL Queries"| MySQLServer
    Interpreter -->|"session read/write"| SQLiteClient
    SQLiteClient -->|"I/O"| SQLiteDB
    Interpreter -->|"render HTML"| FastCGIListener
    FastCGIListener -->|"FCGI Response"| WebServer
    WebServer -->|"HTTP Response"| WebClient

    %% Supporting artifacts
    TestTemplate -.->|used by| Parser
    Makefile -.->|builds| FastCGIListener
    README -.->|docs| FastCGIListener
    Executable -.->|placeholder| FastCGIListener

    %% Click Events
    click FastCGIListener "https://github.com/engwan/qcgi/blob/master/src/qcgi+.cpp"
    click Parser "https://github.com/engwan/qcgi/blob/master/src/parser.cpp"
    click Parser "https://github.com/engwan/qcgi/blob/master/src/parser.h"
    click Interpreter "https://github.com/engwan/qcgi/blob/master/src/interpreter.cpp"
    click Interpreter "https://github.com/engwan/qcgi/blob/master/src/interpreter.h"
    click MySQLClient "https://github.com/engwan/qcgi/blob/master/src/db.cpp"
    click MySQLClient "https://github.com/engwan/qcgi/blob/master/src/db.h"
    click SQLiteClient "https://github.com/engwan/qcgi/blob/master/src/sessions.cpp"
    click SQLiteClient "https://github.com/engwan/qcgi/blob/master/src/sessions.h"
    click Utils "https://github.com/engwan/qcgi/blob/master/src/utils.cpp"
    click Utils "https://github.com/engwan/qcgi/blob/master/src/utils.h"
    click Makefile "https://github.com/engwan/qcgi/tree/master/src/Makefile"
    click README "https://github.com/engwan/qcgi/blob/master/README.md"
    click Executable "https://github.com/engwan/qcgi/tree/master/qcgi+"
    click TestTemplate "https://github.com/engwan/qcgi/blob/master/test.v"

    %% Styles
    classDef external fill:#C8E6C9,stroke:#388E3C,stroke-width:1px
    classDef internal fill:#BBDEFB,stroke:#1976D2,stroke-width:1px
    classDef datastore fill:#FFE0B2,stroke:#F57C00,stroke-width:1px,shape:cylinder
    classDef file fill:#E1BEE7,stroke:#8E24AA,stroke-width:1px
```
