# vincentxgao/civil-tools architecture

> Architecture diagram of the GitHub repository vincentxgao/civil-tools, 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/vincentxgao/civil-tools
- Repository: https://github.com/vincentxgao/civil-tools

## Overview

##### Overall Project Type and Purpose
- This is a Python toolkit targeted at structural engineers. Its purpose is to integrate multiple functions such as:
- Loading building models from YJK-generated .ydb database files (YDBLoader)
- Generating various structural drawings (DXFGenerator)
- Creating report documents such as seismic review reports and stair calculation sheets (ReportGenerator)
- Plotting data figures and images (FigureGenerator)
- Managing constants for CAD, concrete, and steel properties (Const)
- It is essentially a domain-specific library (rather than a full-stack or web application), modularized by functionality for building modeling, visualization, and documentation.

##### File Structure to Identify Main Components
- The primary top-level package is “CivilTools” with sub-packages:
- Const: Likely holds constant definitions and helper utilities used across the toolkit.
- YDBLoader: Includes submodules for “BuildingDefine” (further broken down into Beam, Column, Geometry, GlobalResult, Section, Slab, StairPart) plus the SQLiteConnector for interacting with SQLite databases.
- DXFGenerator: Contains modules for generating various DXF drawings (basic drawings, detailed drawings, drawing attributes, and layer management).
- ReportGenerator: Contains modules for producing different types of reports (e.g., SeismicReport, StairCalculationReport, and individual building blocks like DocParagraph, DocPicture, and DocTable).
- FigureGenerator: Contains modules for producing plots (both using basic PNG and Matplotlib plots), including specialized tools like StairCalculationSheetPNGPlotter.
- Additionally, there are clearly organized tests confirming intended functionality, as well as standard Python packaging files (setup.py, requirements.txt).

##### How to Represent the Architecture
a. Main Components:
- YDBLoader Module
- Contains submodules for Building Definitions (Beam, Column, Geometry, Section, Slab, StairPart) and uses SQLiteConnector.
- It serves as the entry module for reading input “.ydb” files.
- DXFGenerator Module
- Responsible for generating technical drawings in DXF format
- Contains multiple drawing-related modules (BasicDXF, DetailDXF, etc.).
- ReportGenerator Module
- Generates structural reports (seismic reviews, stair calculation reports) by using predefined templates and document components.
- FigureGenerator Module
- Handles production of image-based outputs – charts and plots (PNG) – based on engineering data.
- Const (Constants Module)
- Provides engineering constants and helper routines specific to CAD, concrete, and steel.
b. Relationships and Data Flow:
- YDBLoader reads the .ydb building files and creates model objects that encapsulate building definitions.
- Those model objects (data structures for beams, columns, geometry, etc.) are then used by:
- ReportGenerator to generate calculation reports
- There is an implicit dependency from DXFGenerator and ReportGenerator back to data obtained via YDBLoader.
- The “Const” module is likely used by all other modules to maintain standard parameters (e.g., CAD settings, material properties).
c. Architectural Patterns and Design Principles:
- Modular structure: Each core functionality is encapsulated in its own module, making it easier to extend or modify independently.
- Separation of concerns: Input loading (YDBLoader), data visualization (DXFGenerator and FigureGenerator), and report generation (ReportGenerator) are clearly separated.
- Reusability: Submodules like those in YDBLoader (e.g., building definitions) are divided into components, reflecting an object-oriented approach that could easily be unit-tested (as seen in the tests directory).
d. Relevant Technologies & Frameworks:
- Python is the primary language.
- Likely third-party libraries for drawing (DXF handling), document generation (e.g., python-docx for reports), and plotting (Matplotlib or similar).
- SQLite integration for data management from .ydb files (via the SQLiteConnector submodule).

- Within YDBLoader, optionally nest or list its submodules (BuildingDefine with Beam, Column, Geometry, etc.) and indicate the SQLiteConnector.
- The YDBLoader module outputs structured building data that is consumed by both ReportGenerator and DXFGenerator (and possibly FigureGenerator).
- The “Const” module is accessed by multiple design modules.
- Rectangles for major functional modules (e.g., YDBLoader, DXFGenerator).
- External dependencies (for example, third-party libraries used for plotting or document generation) as small nodes connected to the corresponding module.
- Keep clear labels and directional flows to elucidate how data moves from ingestion to final output document/drawing.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Input Node
    Input["YDB File Input (.ydb)"]:::input

    %% Subgraph for YDBLoader Module
    subgraph "YDBLoader Module"
        YDBLoaderCore["YDBLoader"]:::main
        subgraph "BuildingDefine"
            Beam["Beam"]:::sub
            Column["Column"]:::sub
            Geometry["Geometry"]:::sub
            GlobalResult["GlobalResult"]:::sub
            Section["Section"]:::sub
            Slab["Slab"]:::sub
            StairPart["StairPart"]:::sub
        end
        SQLiteConnector["SQLiteConnector"]:::sub
    end

    %% Main modules
    DXFGen["DXFGenerator"]:::main
    ReportGen["ReportGenerator"]:::main
    FigureGen["FigureGenerator"]:::main
    Const["Const"]:::utility

    %% External nodes for testing and third-party libraries
    Tests["Tests"]:::test

    subgraph "ThirdParty Libraries"
        DXFLib["DXF Library"]:::external
        DocLib["Document Library"]:::external
        PlotLib["Plot Library"]:::external
    end

    %% Connections
    Input -->|"reads"| YDBLoaderCore
    YDBLoaderCore -->|"outputs building model data"| DXFGen
    YDBLoaderCore -->|"outputs building model data"| ReportGen
    YDBLoaderCore -->|"outputs building model data"| FigureGen

    %% Internal YDBLoader connections (to indicate composition)
    YDBLoaderCore --> Beam
    YDBLoaderCore --> Column
    YDBLoaderCore --> Geometry
    YDBLoaderCore --> GlobalResult
    YDBLoaderCore --> Section
    YDBLoaderCore --> Slab
    YDBLoaderCore --> StairPart
    YDBLoaderCore --> SQLiteConnector

    %% Modules using constants
    DXFGen -->|"uses constants"| Const
    ReportGen -->|"uses constants"| Const
    FigureGen -->|"uses constants"| Const

    %% Modules verified by tests
    DXFGen -- "verifiedBy" --> Tests
    ReportGen -- "verifiedBy" --> Tests
    FigureGen -- "verifiedBy" --> Tests
    YDBLoaderCore -- "verifiedBy" --> Tests

    %% Third Party Libraries Dependencies
    DXFGen -->|"uses"| DXFLib
    ReportGen -->|"uses"| DocLib
    FigureGen -->|"uses"| PlotLib

    %% Click Events
    click Const "https://github.com/vincentxgao/civil-tools/tree/dev/CivilTools/Const"
    click YDBLoaderCore "https://github.com/vincentxgao/civil-tools/tree/dev/CivilTools/YDBLoader"
    click Beam "https://github.com/vincentxgao/civil-tools/tree/dev/CivilTools/YDBLoader/BuildingDefine/Beam"
    click Column "https://github.com/vincentxgao/civil-tools/tree/dev/CivilTools/YDBLoader/BuildingDefine/Column"
    click Geometry "https://github.com/vincentxgao/civil-tools/tree/dev/CivilTools/YDBLoader/BuildingDefine/Geometry"
    click GlobalResult "https://github.com/vincentxgao/civil-tools/tree/dev/CivilTools/YDBLoader/BuildingDefine/GlobalResult"
    click Section "https://github.com/vincentxgao/civil-tools/tree/dev/CivilTools/YDBLoader/BuildingDefine/Section"
    click Slab "https://github.com/vincentxgao/civil-tools/tree/dev/CivilTools/YDBLoader/BuildingDefine/Slab"
    click StairPart "https://github.com/vincentxgao/civil-tools/tree/dev/CivilTools/YDBLoader/BuildingDefine/StairPart"
    click SQLiteConnector "https://github.com/vincentxgao/civil-tools/tree/dev/CivilTools/YDBLoader/SQLiteConnector"
    click DXFGen "https://github.com/vincentxgao/civil-tools/tree/dev/CivilTools/DXFGenerator"
    click ReportGen "https://github.com/vincentxgao/civil-tools/tree/dev/CivilTools/ReportGenerator"
    click FigureGen "https://github.com/vincentxgao/civil-tools/tree/dev/CivilTools/FigureGenerator"

    %% Styles
    classDef main fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef sub fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef utility fill:#FFF9C4,stroke:#F9A825,stroke-width:2px;
    classDef input fill:#FFCCBC,stroke:#BF360C,stroke-width:2px;
    classDef external fill:#D1C4E9,stroke:#4527A0,stroke-width:2px;
    classDef test fill:#FFCDD2,stroke:#C62828,stroke-width:2px;
```
