# pcisar/fdb architecture

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

- Interactive diagram: https://gitdiagram.com/pcisar/fdb
- Repository: https://github.com/pcisar/fdb

## Overview

##### Project type and purpose
- This is a Python library (FDB) that implements the Python DB‐API 2.0 for the Firebird RDBMS and exposes the complete native client API.
- It is not a full‐stack application but a driver library with submodules for schema access, monitoring, trace parsing, logging, and services utilities.

##### File structure
- Top-level:
- fdb/           ← the main Python package
- sphinx/        ← documentation source for Sphinx
- test/          ← unit tests and sample database files
- setup.py, requirements.txt, setup.cfg
- In fdb/:
- fbcore.py      ← core low-level bindings and connection management
- ibase.py       ← legacy client API wrapper
- blr.py, gstat.py, monitor.py, trace.py, services.py, schema.py, log.py, utils.py
– each submodule encapsulates a distinct area of Firebird functionality
- sphinx contains conf.py, static assets, layout templates to build HTML/PDF docs
- test contains .fdb files (embedded test DBs), expected outputs, and testfdb.py

##### Extract insights from README
- FDB supports:
- DB-API 2.0 operations (connect, cursor, execute, fetch)
- Low-level client calls for advanced features
- Automatic data conversions, BLOBs, arrays, events, distributed transactions
- Schema inspection, monitoring tables, extract service output, trace/audit log parsing
- Key external dependency: Firebird client library (libfbclient)

##### Main components
a. Python Application Layer (end user code or third-party app)
b. FDB Python Package
- API façade (DB-API compliance modules in fdb/__init__.py)
- Core binding layer (fbcore.py, ibase.py) → calls into the Firebird client C API
- Feature modules (schema, monitor, trace, gstat, services, log, utils)
c. Native Firebird Client Library (C library, libfbclient.so/dll)
d. Firebird Server (database engine)
e. Auxiliary components
- Sphinx documentation generator
- Test harness (test suite + sample databases)

##### Relationships and interactions
- Feature modules ↔ Core layer (they request data or perform actions via core)
- Documentation and tests are external processes that consume the FDB package code but do not form part of the runtime data path

##### Architectural patterns and principles
- Layered architecture: API → binding → native client → server
- Modular design: submodules each handle a distinct cross-cutting concern
- Separation of concerns: DB-API compliance code is distinct from low-level calls
- Extensibility points: utility modules (trace, gstat, services) can be used independently

##### Essential details to capture
- Public API entry points (connect, cursor, execute)
- Core runtime binding to the Firebird client C API
- Each feature module’s dependency on the core layer
- External library and server boundaries
- Auxiliary tooling (docs, tests) as non-runtime flows

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Application
    App["Python Application"]:::external

    %% FDB Python Package
    subgraph "FDB Python Package"
        API["API Façade\n(DB-API compliance)"]:::api
        subgraph "Core Binding Layer"
            fbcore["Core Binding Layer\nfbcore.py"]:::core
            ibase["Core Binding Layer\nibase.py"]:::core
        end
        subgraph "Feature Modules"
            schema["Schema Access\nschema.py"]:::feature
            monitor["Monitoring Tables\nmonitor.py"]:::feature
            trace["Trace & Audit Parsing\ntrace.py"]:::feature
            gstat["Performance Stats\ngstat.py"]:::feature
            services["Services Utilities\nservices.py"]:::feature
            log["Logging Utilities\nlog.py"]:::feature
            blr["BLR Handling\nblr.py"]:::feature
            utils["Helper Utilities\nutils.py"]:::feature
        end
    end

    %% External Dependencies
    clientlib["Native Client Library\nlibfbclient"]:::external
    server["Firebird Server"]:::external

    %% Auxiliary Processes
    sphinx["Sphinx Documentation"]:::external
    test["Test Harness"]:::external

    %% Connections
    App -->|"connect,execute"| API
    API -->|"calls"| fbcore
    API -->|"calls"| ibase
    fbcore -->|"C API calls"| clientlib
    ibase -->|"C API calls"| clientlib
    clientlib -->|"protocol"| server

    schema -->|"schema queries"| fbcore
    monitor -->|"monitor queries"| fbcore
    trace -->|"trace events"| fbcore
    gstat -->|"statistics calls"| fbcore
    services -->|"service calls"| fbcore
    log -->|"logging hooks"| fbcore
    blr -->|"BLR processing"| fbcore
    utils -->|"utility functions"| fbcore

    sphinx -.-> API
    test -.-> API

    %% Click Events
    click API "https://github.com/pcisar/fdb/blob/master/fdb/__init__.py"
    click fbcore "https://github.com/pcisar/fdb/blob/master/fdb/fbcore.py"
    click ibase "https://github.com/pcisar/fdb/blob/master/fdb/ibase.py"
    click schema "https://github.com/pcisar/fdb/blob/master/fdb/schema.py"
    click monitor "https://github.com/pcisar/fdb/blob/master/fdb/monitor.py"
    click trace "https://github.com/pcisar/fdb/blob/master/fdb/trace.py"
    click gstat "https://github.com/pcisar/fdb/blob/master/fdb/gstat.py"
    click services "https://github.com/pcisar/fdb/blob/master/fdb/services.py"
    click log "https://github.com/pcisar/fdb/blob/master/fdb/log.py"
    click blr "https://github.com/pcisar/fdb/blob/master/fdb/blr.py"
    click utils "https://github.com/pcisar/fdb/blob/master/fdb/utils.py"
    click sphinx "https://github.com/pcisar/fdb/tree/master/sphinx/"
    click test "https://github.com/pcisar/fdb/tree/master/test/"

    %% Styles
    classDef api fill:#blue,stroke:#000,color:#fff;
    classDef core fill:#f90,stroke:#000,color:#000;
    classDef feature fill:#9f6,stroke:#000,color:#000;
    classDef external fill:#ccc,stroke:#666,color:#000;
```
