# topmod-org/pytopmod-core architecture

> Architecture diagram of the GitHub repository topmod-org/pytopmod-core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/topmod-org/pytopmod-core
- Repository: https://github.com/topmod-org/pytopmod-core

## Overview

##### Main Components Organization

a. Core Layer (Bottom):
- Basic geometric elements (Vertex, Edge, Face, HalfEdge, Corner)
- Utility modules (CircularList, Keystore, Geometry)

b. Mesh Representation Layer (Middle):
- Create two parallel containers labeled:
- "DCEL (Doubly-Connected Edge List)" implementation
- "DLFL (Doubly-Linked Face List)" implementation

c. Operations Layer (Top):
- Operations and algorithms that work on these mesh representations

##### Specific Components Detail

For DCEL Module:
- ┌─ DCEL Implementation ─────┐
- Mesh                    │
- Primitives             │
- Operators              │
- OBJ I/O                │
- ┘

For DLFL Module:
- ┌─ DLFL Implementation ────┐
- Mesh                   │
- Primitives            │
- Operators             │
- OBJ I/O               │
- Subdivision           │
- ┘

##### Important Elements
- A "File I/O" section showing OBJ file format support
- Type system (py.typed) indication
- Relationship with external demo scripts

##### Technical Details to Highlight
- That this is a src-layout Python package
- Presence of type checking (mypy support)
- Extension points for future algorithms

##### Implementation Notes
- Use UML-like notation where appropriate
- Notes about the optimization focus (readability over performance)

- The clear separation between core geometric primitives and mesh representations
- The parallel implementation of DCEL and DLFL approaches
- The extensible nature of the operations system
- The type-safe design of the system

Remember to include a note about the development tools integration (black, flake8, mypy, isort) as they are integral to the project's architecture and development workflow.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Operations Layer"
        Operations["Operations & Algorithms"]:::operations
        FileIO["File I/O (OBJ Format)"]:::io
        Demo["Demo Scripts"]:::demo
        click Demo "https://github.com/topmod-org/pytopmod-core/tree/main/scripts"
    end

    subgraph "Mesh Representation Layer"
        subgraph "DCEL Implementation"
            DCELMesh["DCEL Mesh"]:::mesh
            DCELPrim["DCEL Primitives"]:::mesh
            DCELOp["DCEL Operators"]:::mesh
            DCELIO["DCEL OBJ I/O"]:::mesh
            click DCELMesh "https://github.com/topmod-org/pytopmod-core/blob/main/src/pytopmod/core/dcel/mesh.py"
            click DCELPrim "https://github.com/topmod-org/pytopmod-core/blob/main/src/pytopmod/core/dcel/primitives.py"
            click DCELOp "https://github.com/topmod-org/pytopmod-core/blob/main/src/pytopmod/core/dcel/operators.py"
            click DCELIO "https://github.com/topmod-org/pytopmod-core/blob/main/src/pytopmod/core/dcel/obj_io.py"
        end

        subgraph "DLFL Implementation"
            DLFLMesh["DLFL Mesh"]:::mesh
            DLFLPrim["DLFL Primitives"]:::mesh
            DLFLOp["DLFL Operators"]:::mesh
            DLFLIO["DLFL OBJ I/O"]:::mesh
            DLFLSub["DLFL Subdivision"]:::mesh
            click DLFLMesh "https://github.com/topmod-org/pytopmod-core/blob/main/src/pytopmod/core/dlfl/mesh.py"
            click DLFLPrim "https://github.com/topmod-org/pytopmod-core/blob/main/src/pytopmod/core/dlfl/primitives.py"
            click DLFLOp "https://github.com/topmod-org/pytopmod-core/blob/main/src/pytopmod/core/dlfl/operators.py"
            click DLFLIO "https://github.com/topmod-org/pytopmod-core/blob/main/src/pytopmod/core/dlfl/obj_io.py"
            click DLFLSub "https://github.com/topmod-org/pytopmod-core/blob/main/src/pytopmod/core/dlfl/operations/subdivision.py"
        end
    end

    subgraph "Core Layer"
        subgraph "Basic Geometric Elements"
            Vertex["Vertex"]:::core
            Edge["Edge"]:::core
            Face["Face"]:::core
            HalfEdge["HalfEdge"]:::core
            Corner["Corner"]:::core
            click Vertex "https://github.com/topmod-org/pytopmod-core/blob/main/src/pytopmod/core/vertex.py"
            click Edge "https://github.com/topmod-org/pytopmod-core/blob/main/src/pytopmod/core/edge.py"
            click Face "https://github.com/topmod-org/pytopmod-core/blob/main/src/pytopmod/core/face.py"
            click HalfEdge "https://github.com/topmod-org/pytopmod-core/blob/main/src/pytopmod/core/half_edge.py"
            click Corner "https://github.com/topmod-org/pytopmod-core/blob/main/src/pytopmod/core/corner.py"
        end

        subgraph "Utility Modules"
            CircList["CircularList"]:::util
            Keystore["Keystore"]:::util
            Geometry["Geometry"]:::util
            TypeSystem["Type System (py.typed)"]:::util
            click CircList "https://github.com/topmod-org/pytopmod-core/blob/main/src/pytopmod/core/circular_list.py"
            click Keystore "https://github.com/topmod-org/pytopmod-core/blob/main/src/pytopmod/core/keystore.py"
            click Geometry "https://github.com/topmod-org/pytopmod-core/blob/main/src/pytopmod/core/geometry.py"
            click TypeSystem "https://github.com/topmod-org/pytopmod-core/blob/main/src/pytopmod/py.typed"
        end
    end

    %% Relationships
    Operations --> DCELMesh
    Operations --> DLFLMesh
    FileIO --> DCELIO
    FileIO --> DLFLIO
    Demo --> Operations

    DCELMesh --> Vertex
    DCELMesh --> Edge
    DCELMesh --> Face
    DCELMesh --> HalfEdge
    
    DLFLMesh --> Vertex
    DLFLMesh --> Edge
    DLFLMesh --> Face
    DLFLMesh --> Corner

    %% Styles
    classDef core fill:#a8d0e6,stroke:#333,stroke-width:2px
    classDef util fill:#8860d0,stroke:#333,stroke-width:2px
    classDef mesh fill:#84ceeb,stroke:#333,stroke-width:2px
    classDef operations fill:#f8a978,stroke:#333,stroke-width:2px
    classDef io fill:#c1c8e4,stroke:#333,stroke-width:2px
    classDef demo fill:#5ab9ea,stroke:#333,stroke-width:2px
```
