# toddbirchard/ghost-webhook-api architecture

> Architecture diagram of the GitHub repository toddbirchard/ghost-webhook-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/toddbirchard/ghost-webhook-api
- Repository: https://github.com/toddbirchard/ghost-webhook-api

## Overview

##### Main Components

a) Core API Layer:
- FastAPI application at the center
- Endpoints into logical groups as shown in the app directory (posts, analytics, images, accounts, etc.)

b) External Services Integration:
- Ghost CMS (primary integration)
- Cloud Services:
- Google Cloud Storage (for CDN/images)
- BigQuery (for analytics)
- Email Services (Mailgun)
- Analytics Services:
- Plausible
- Algolia
- Mixpanel
- Authentication Services (Netlify Auth)
- Notification Services (SMS)
- Github API

c) Database Layer:
- SQL Database (shown by SQLAlchemy usage)
- Query management system (database/queries directory)

##### Component Relationships

**1. Incoming Webhooks:**
- Ghost CMS -> API Endpoints -> Business Logic -> Database/External Services

**2. Data Flows:**
- Image Processing: API -> GCS -> CDN
- Analytics: BigQuery/Algolia -> API -> Database
- Notifications: API -> Mail/SMS Services
- User Management: Netlify Auth -> API -> Ghost Members

##### Specific Implementation Details

a) API Layer (Top):
- Endpoints by feature modules (posts, analytics, images, etc.)
- Webhook entry points

b) Processing Layer (Middle):
- Business logic modules
- Image optimization pipeline
- Analytics aggregation
- Notification handling

c) Storage Layer (Bottom):
- Database with tables/models
- Query management system
- External storage (GCS)

##### Important Architectural Patterns to Highlight

- Modular design (shown by clear separation in app directory)
- Service-oriented architecture (multiple external service integrations)
- Event-driven architecture (webhook-based)
- Data pipeline patterns (analytics and image processing)

##### Technical Details

- Python 3.10+ runtime
- FastAPI framework
- SQLAlchemy ORM
- Pydantic models for data validation
- Google Cloud integration
- Ghost API v5.0.0 compatibility

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph API_Layer
        API[FastAPI Application]:::api
        WebhookEndpoints[Webhook Endpoints]:::api
        PostsAPI[Posts API]:::api
        AnalyticsAPI[Analytics API]:::api
        ImagesAPI[Images API]:::api
        AccountsAPI[Accounts API]:::api
    end

    subgraph External_Services
        Ghost[Ghost CMS]:::external
        GCS[Google Cloud Storage]:::external
        BigQuery[BigQuery]:::external
        Mailgun[Mailgun]:::external
        Plausible[Plausible]:::external
        Algolia[Algolia]:::external
        Mixpanel[Mixpanel]:::external
        NetlifyAuth[Netlify Auth]:::external
        SMS[SMS Service]:::external
        Github[Github API]:::external
    end

    subgraph Processing_Layer
        ImageProcessor[Image Processing]:::process
        AnalyticsAggregator[Analytics Aggregation]:::process
        NotificationHandler[Notification Handler]:::process
        PostManager[Post Manager]:::process
        Newsletter[Newsletter System]:::process
    end

    subgraph Database_Layer
        DB[(SQL Database)]:::database
        QueryManager[Query Management]:::database
        Models[Database Models]:::database
        CRUD[CRUD Operations]:::database
    end

    %% Core Connections
    Ghost --> WebhookEndpoints
    WebhookEndpoints --> API
    API --> |Routes| PostsAPI & AnalyticsAPI & ImagesAPI & AccountsAPI

    %% Processing Flows
    PostsAPI --> PostManager
    ImagesAPI --> ImageProcessor
    AnalyticsAPI --> AnalyticsAggregator
    AccountsAPI --> NotificationHandler

    %% External Service Connections
    ImageProcessor --> GCS
    AnalyticsAggregator --> BigQuery & Algolia & Plausible & Mixpanel
    NotificationHandler --> Mailgun & SMS
    PostManager --> Github
    AccountsAPI --> NetlifyAuth

    %% Database Connections
    PostManager & ImageProcessor & AnalyticsAggregator & NotificationHandler --> CRUD
    CRUD --> DB
    QueryManager --> DB
    Models --> DB

    %% Click Events
    click API "https://github.com/toddbirchard/ghost-webhook-api/blob/master/asgi.py"
    click Ghost "https://github.com/toddbirchard/ghost-webhook-api/blob/master/clients/ghost.py"
    click GCS "https://github.com/toddbirchard/ghost-webhook-api/blob/master/clients/gcs.py"
    click Mailgun "https://github.com/toddbirchard/ghost-webhook-api/blob/master/clients/mail.py"
    click SMS "https://github.com/toddbirchard/ghost-webhook-api/blob/master/clients/sms.py"
    click ImageProcessor "https://github.com/toddbirchard/ghost-webhook-api/blob/master/clients/img.py"
    click Algolia "https://github.com/toddbirchard/ghost-webhook-api/blob/master/app/analytics/algolia.py"
    click Plausible "https://github.com/toddbirchard/ghost-webhook-api/blob/master/app/analytics/plausible.py"
    click Mixpanel "https://github.com/toddbirchard/ghost-webhook-api/blob/master/app/newsletter/mixpanel.py"
    click Github "https://github.com/toddbirchard/ghost-webhook-api/tree/master/app/github/"
    click Models "https://github.com/toddbirchard/ghost-webhook-api/blob/master/database/models.py"
    click CRUD "https://github.com/toddbirchard/ghost-webhook-api/blob/master/database/crud.py"
    click DB "https://github.com/toddbirchard/ghost-webhook-api/blob/master/database/sql_db.py"
    click PostManager "https://github.com/toddbirchard/ghost-webhook-api/blob/master/app/posts/update.py"
    click QueryManager "https://github.com/toddbirchard/ghost-webhook-api/tree/master/database/queries/"
    click Newsletter "https://github.com/toddbirchard/ghost-webhook-api/blob/master/app/newsletter/newsletter.py"

    %% Styling
    classDef api fill:#2374ab
    classDef external fill:#7dba84
    classDef process fill:#a239ca
    classDef database fill:#ff8c42

    %% Legend
    subgraph Legend
        L1[API Components]:::api
        L2[External Services]:::external
        L3[Processing Modules]:::process
        L4[Database Components]:::database
    end
```
