How yaokisan/zenjidou-gijiroku-gen works
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.