# sven-bo/fasthtml-guestbook architecture

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

- Interactive diagram: https://gitdiagram.com/sven-bo/fasthtml-guestbook
- Repository: https://github.com/sven-bo/fasthtml-guestbook

## Overview

##### Main Components

a. Client-Side Layer:
- HTMX-enabled Frontend
- Browser Components
- Real-time update capabilities

b. Server-Side Layer:
- FastHTML Application Server (Python)
- Route Handlers
- Template Engine

c. External Services:
- Google Sheets API (as Database)
- Google Drive API

- [Client Browser] ←→ [FastHTML Server] ←→ [Google Sheets API]
- ↑                     ↑                      ↑

- HTMX Updates         Template Engine       Credentials.json

##### Component Details

a. Client Layer (Top):
- Real-time update paths
- User interaction points

b. Server Layer (Middle):
- FastHTML application server
- Route handlers for form submissions
- Template rendering engine
- Authentication handling

c. Database Layer (Bottom):
- Google Sheets API connection
- Data storage and retrieval flows
- API authentication flow

##### Important Flows to Highlight

a. User Input Flow:
- Form submission
- HTMX request handling
- Server processing
- Google Sheets update
- Real-time page update

b. Authentication Flow:
- Credentials.json usage
- Google API authentication
- Token management

##### Additional Elements

- Version information for key components
- Error handling paths
- Asynchronous operations
- Security boundaries

##### Technical Details

- Port number (5001)
- API endpoints
- Data flow directions
- Authentication points
- Real-time update mechanisms

##### Notes for Implementation

- Use consistent symbols throughout
- Brief annotations where necessary
- Both synchronous and asynchronous paths
- Error handling flows

- The simplicity of the architecture
- The real-time nature of updates via HTMX
- The unique use of Google Sheets as a database
- Security considerations for API access
- The separation of concerns between client, server, and external services

Remember to maintain a balance between detail and clarity, as this is a relatively straightforward application with some interesting architectural choices (particularly the use of Google Sheets as a database and HTMX for real-time updates).

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Client
        Browser["Web Browser"]
        HTMX["HTMX Frontend"]:::frontend
    end

    subgraph Server
        FastHTML["FastHTML Server"]:::server
        Routes["Route Handlers"]:::server
        Templates["Template Engine"]:::server
        Auth["Authentication Handler"]:::security
    end

    subgraph External
        GSheetsAPI["Google Sheets API"]:::external
        GDriveAPI["Google Drive API"]:::external
        Creds["credentials.json"]:::security
    end

    %% Connections
    Browser <--> HTMX
    HTMX <--> |"HTMX Requests"| FastHTML
    FastHTML <--> Routes
    Routes <--> Templates
    Routes <--> Auth
    Auth <--> Creds
    Auth <--> GSheetsAPI
    Auth <--> GDriveAPI

    %% Click Events
    click FastHTML "https://github.com/Sven-Bo/fasthtml-guestbook/blob/main/main.py"
    click Routes "https://github.com/Sven-Bo/fasthtml-guestbook/blob/main/main.py"
    click HTMX "https://github.com/Sven-Bo/fasthtml-guestbook/tree/main/assets"

    %% Styles
    classDef frontend fill:#2196F3,stroke:#1565C0,color:white
    classDef server fill:#4CAF50,stroke:#2E7D32,color:white
    classDef external fill:#FFC107,stroke:#FFA000,color:black
    classDef security fill:#F44336,stroke:#C62828,color:white

    %% Legend
    subgraph Legend
        L1["Frontend Components"]:::frontend
        L2["Server Components"]:::server
        L3["External Services"]:::external
        L4["Security Components"]:::security
    end
```
