# arskode/basilico architecture

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

- Interactive diagram: https://gitdiagram.com/arskode/basilico
- Repository: https://github.com/arskode/basilico

## Overview

##### Project Type Analysis
This is a specialized Python library focused on HTML generation with support for modern web frameworks and JavaScript libraries (HTMX and Alpine.js). It's designed to be a dependency-free tool that bridges Python and HTML generation.

##### Main Components

Core Components Layer:
- Node System (node.py): The fundamental building block
- Elements System (elements.py): HTML element definitions
- Attributes System (attributes.py): HTML attribute handling
- Components System (components.py): Reusable component logic

Integration Layer:
- HTMX Integration (htmx.py)
- Alpine.js Integration (alpine.py)

**┌─────────────────────────────────────────────────┐**
- Client Applications               │
- (FastAPI, Django, or other Python web apps)    │
- ┘
- ↑
**┌─────────────────────────────────────────────────┐**
- Basilico Public API                 │
- ┬─────────────────┬─────────────────┤
- Components │     Elements    │    Attributes    │
- ┴─────────────────┴─────────────────┘
- ↑
**┌─────────────────────────────────────────────────┐**
- Core Node System                   │
- ┘
- ↑
**┌─────────────────────────────────────────────────┐**
- Integration Modules                   │
- ┬───────────────────────────┤
- HTMX           │        Alpine.js          │
- ┴───────────────────────────┘

##### Important Details

a. Component Relationships:
- How Node serves as the base class for all HTML elements
- How Components utilize Elements and Attributes
- Demonstrate how HTMX and Alpine.js integrations extend the base functionality

b. Data Flow:
- Flow from Python code to HTML output
- Type safety mechanisms (py.typed file)
- How components can be nested and composed

##### Implementation Notes
- Version compatibility information
- Integration points with web frameworks
- Zero-dependency nature of the library

##### Key Relationships to Emphasize
- The hierarchical nature of the Node system
- How attributes are applied to elements
- The relationship between components and their HTML output
- Integration points with HTMX and Alpine.js

- Clear hierarchical representation
- Text annotations for additional context

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client["Client Applications"]
        FastAPI["FastAPI Apps"]
        Django["Django Apps"]
        Other["Other Python Web Apps"]
    end

    subgraph API["Basilico Public API"]
        Entry["Package Entry Point"]:::entry
        Components["Components System"]:::components
        Elements["Elements System"]:::elements
        Attributes["Attributes System"]:::attributes
    end

    subgraph Core["Core Layer"]
        Node["Node System"]:::node
        TypeSafety["Type Safety Mechanism"]:::type
    end

    subgraph Integration["Integration Modules"]
        HTMX["HTMX Integration"]:::htmx
        Alpine["Alpine.js Integration"]:::alpine
    end

    subgraph Tests["Test Suite"]
        ComponentTests["Components Tests"]:::test
        ElementTests["Elements Tests"]:::test
        AttributeTests["Attributes Tests"]:::test
        HTMXTests["HTMX Tests"]:::test
        AlpineTests["Alpine.js Tests"]:::test
        PerfTests["Performance Tests"]:::test
    end

    FastAPI --> API
    Django --> API
    Other --> API

    Entry --> Components
    Entry --> Elements
    Entry --> Attributes

    Components --> Node
    Elements --> Node
    Attributes --> Node

    Node --> HTMX
    Node --> Alpine

    ComponentTests -.-> Components
    ElementTests -.-> Elements
    AttributeTests -.-> Attributes
    HTMXTests -.-> HTMX
    AlpineTests -.-> Alpine
    PerfTests -.-> Node

    %% Click events for component mapping
    click Node "https://github.com/arskode/basilico/blob/main/src/basilico/node.py"
    click Elements "https://github.com/arskode/basilico/blob/main/src/basilico/elements.py"
    click Attributes "https://github.com/arskode/basilico/blob/main/src/basilico/attributes.py"
    click Components "https://github.com/arskode/basilico/blob/main/src/basilico/components.py"
    click HTMX "https://github.com/arskode/basilico/blob/main/src/basilico/htmx.py"
    click Alpine "https://github.com/arskode/basilico/blob/main/src/basilico/alpine.py"
    click TypeSafety "https://github.com/arskode/basilico/blob/main/src/basilico/py.typed"
    click Entry "https://github.com/arskode/basilico/blob/main/src/basilico/__init__.py"
    click ComponentTests "https://github.com/arskode/basilico/blob/main/src/tests/test_components.py"
    click ElementTests "https://github.com/arskode/basilico/blob/main/src/tests/test_elements.py"
    click AttributeTests "https://github.com/arskode/basilico/blob/main/src/tests/test_attributes.py"
    click HTMXTests "https://github.com/arskode/basilico/blob/main/src/tests/test_htmx.py"
    click AlpineTests "https://github.com/arskode/basilico/blob/main/src/tests/test_alpine.py"
    click PerfTests "https://github.com/arskode/basilico/blob/main/src/tests/test_benchmarks.py"

    %% Styling
    classDef default fill:#f9f9f9,stroke:#333,stroke-width:2px
    classDef node fill:#b3e0ff,stroke:#333
    classDef components fill:#90EE90,stroke:#333
    classDef elements fill:#98FB98,stroke:#333
    classDef attributes fill:#98FB98,stroke:#333
    classDef entry fill:#98FB98,stroke:#333
    classDef type fill:#b3e0ff,stroke:#333
    classDef htmx fill:#FFB366,stroke:#333
    classDef alpine fill:#FFB366,stroke:#333
    classDef test fill:#E6E6E6,stroke:#333
```
