# yaokisan/zenjidou-gijiroku-gen architecture

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

- Interactive diagram: https://gitdiagram.com/yaokisan/zenjidou-gijiroku-gen
- Repository: https://github.com/yaokisan/zenjidou-gijiroku-gen

## Overview

##### Project Type and Purpose
- This is a full-stack web application developed in Python using Flask. Its main purpose is to receive Notta transcription data via a Zapier webhook, process it using one of several AI models (Google Gemini, Anthropic Claude, or OpenAI ChatGPT), auto-generate meeting minutes, and then store the results in Notion.
- The README and file tree indicate that the application supports key integrations (Notta, AI services, Notion, and Zapier) and includes a user interface for settings and viewing generated meeting minutes.

##### File Structure Analysis
- Key Directories:
- app/:
▫ __init__.py – The application factory.
▫ models.py – SQLAlchemy models for data persistence.
▫ routes/ – Contains API endpoints:
- webhook.py (for handling Zapier POST requests),
- results.py (for status and fetched results),
- settings.py (for managing configuration and AI model selection).
▫ services/ – Houses service modules for external integrations:
- ai_service.py (communication with various AI models),
- notion_service.py (handling Notion API interactions).
- app/templates/ and app/static/ – Provide the front-end views (Jinja2 templates) and supporting CSS/JS.
- Additional components:
- api/ directory suggests additional endpoint or experimental API functionality.
- Docs and tests directories confirm documentation, testing strategies, and debugging support.
- run.py and several scripts (like app_debug.py) indicate how the application is started and debugged.

##### Key Components
a. User Interface Layer:
- Web Browser: Accesses the application via HTTP (e.g., settings page and results page).
- Templates and Static Assets: Located under app/templates and app/static.
b. API and Web Application Layer:
- Flask Application: The core application (initialized in app/__init__.py) that manages routing.
- Endpoints under app/routes:
- /api/webhook (handled by webhook.py): Receives data from Zapier.
- /api/status/<history_id> (in results.py): Allows status tracking.
- /settings: For user configuration of AI model and Notion page parameters.
c. Business Logic & Service Layer:
- AI Service (app/services/ai_service.py): Manages selection and communication with external AI services (Google Gemini, Anthropic Claude, OpenAI ChatGPT).
- Notion Service (app/services/notion_service.py): Direct API calls to Notion for creating/storing meeting minutes.
d. Data Persistence:
- SQLAlchemy Models (in app/models.py) - Represent meeting minute data, settings, and history.
e. External Integrations:
- Notta: Source of the transcription data (via Zapier integration).
- Zapier: Acts as a middleware to deliver data to the /api/webhook endpoint.
- External APIs: AI models and Notion’s API for content generation and persistence.
f. Auxiliary Components:
- Test Scripts: (tests/test_notion.py, tests/test_webhook.py) for integration and unit testing.
- Debug Tools: app_debug.py and scripts/app_debug.py help diagnose configuration issues.

##### Relationships and Data Flow
- Zapier forwards the payload to the /api/webhook endpoint of your Flask app.
- The webhook handler processes the incoming data and then calls the AI service to generate meeting minutes.
- Once the meeting minutes are generated, the Notion service is invoked to store the minutes in Notion.
- The resulting data is stored in the database (using SQLAlchemy models) and can later be retrieved and viewed via the results page.
- The settings endpoint allows updates to preferences like AI model selection and Notion API settings, impacting how the services operate.

##### Architectural Patterns and Design Principles
- Use of the Application Factory Pattern (Flask’s __init__.py) for initializing the app.
- Separation of concerns:
- Routes are clearly separated from service logic.
- Service layers for external API calls maintain clean abstractions.
- Modular design: Each feature (e.g., AI, Notion, webhook handling) is in its own module, which aids maintainability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External Systems"
        N["Notta (Transcription)"]:::external
        Z["Zapier (Webhook)"]:::external
        AExt["AI External Services"]:::external
        NotionExt["Notion API"]:::external
    end

    %% User Interface Layer
    subgraph "User Interface"
        Browser["Web Browser"]:::frontend
        Templates["Templates"]:::frontend
        Static["Static Assets"]:::frontend
    end

    %% API & Web Application Layer
    subgraph "API & Web Application"
        FlaskApp["Flask Application"]:::backend
        Webhook["Webhook Endpoint (/api/webhook)"]:::backend
        Status["Status Endpoint (/api/status/{history_id})"]:::backend
        Settings["Settings Endpoint (/settings)"]:::backend
    end

    %% Business Logic & Service Layer
    subgraph "Business Logic & Services"
        AIService["AI Service"]:::backend
        NotionService["Notion Service"]:::backend
    end

    %% Data Persistence
    subgraph "Data Persistence"
        Database["SQLAlchemy Models/Database"]:::database
    end

    %% Auxiliary Tools
    subgraph "Auxiliary Tools"
        TestNotion["Test: test_notion.py"]:::aux
        TestWebhook["Test: test_webhook.py"]:::aux
        DebugApp["Debug: app_debug.py"]:::aux
        DebugScript["Debug: scripts/app_debug.py"]:::aux
    end

    %% Data Flow / Relationships
    N -->|"sends_payload"| Z
    Z -->|"triggers"| Webhook
    Webhook -->|"calls_AI_service"| AIService
    AIService -->|"generates_minutes"| NotionService
    NotionService -->|"stores_data"| Database

    FlaskApp -->|"routes_to"| Webhook
    FlaskApp -->|"routes_to"| Status
    FlaskApp -->|"routes_to"| Settings

    Browser -->|"renders"| Templates
    Browser -->|"renders"| Static
    Browser -->|"sends_HTTP_req"| FlaskApp

    Status -->|"fetches_data"| Database
    Settings -->|"updates_settings"| Database

    TestNotion -->|"validates"| FlaskApp
    TestWebhook -->|"validates"| FlaskApp
    DebugApp -->|"diagnoses"| FlaskApp
    DebugScript -->|"diagnoses"| FlaskApp

    %% Click Events
    click Templates "https://github.com/yaokisan/zenjidou-gijiroku-gen/tree/main/app/templates"
    click Static "https://github.com/yaokisan/zenjidou-gijiroku-gen/tree/main/app/static"
    click FlaskApp "https://github.com/yaokisan/zenjidou-gijiroku-gen/blob/main/app/__init__.py"
    click Webhook "https://github.com/yaokisan/zenjidou-gijiroku-gen/blob/main/app/routes/webhook.py"
    click Status "https://github.com/yaokisan/zenjidou-gijiroku-gen/blob/main/app/routes/results.py"
    click Settings "https://github.com/yaokisan/zenjidou-gijiroku-gen/blob/main/app/routes/settings.py"
    click AIService "https://github.com/yaokisan/zenjidou-gijiroku-gen/blob/main/app/services/ai_service.py"
    click NotionService "https://github.com/yaokisan/zenjidou-gijiroku-gen/blob/main/app/services/notion_service.py"
    click Database "https://github.com/yaokisan/zenjidou-gijiroku-gen/blob/main/app/models.py"
    click TestNotion "https://github.com/yaokisan/zenjidou-gijiroku-gen/blob/main/tests/test_notion.py"
    click TestWebhook "https://github.com/yaokisan/zenjidou-gijiroku-gen/blob/main/tests/test_webhook.py"
    click DebugApp "https://github.com/yaokisan/zenjidou-gijiroku-gen/blob/main/app_debug.py"
    click DebugScript "https://github.com/yaokisan/zenjidou-gijiroku-gen/blob/main/scripts/app_debug.py"

    %% Styles
    classDef external fill:#FFCCCB,stroke:#B22222,stroke-width:2px;
    classDef frontend fill:#ADD8E6,stroke:#00008B,stroke-width:2px;
    classDef backend fill:#90EE90,stroke:#006400,stroke-width:2px;
    classDef database fill:#FFFACD,stroke:#DAA520,stroke-width:2px;
    classDef aux fill:#D3D3D3,stroke:#696969,stroke-width:2px;
```
