# trinity-syt-security/testlinetogemini architecture

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

- Interactive diagram: https://gitdiagram.com/trinity-syt-security/testlinetogemini
- Repository: https://github.com/trinity-syt-security/testlinetogemini

## Overview

##### Project Type and Purpose
- This is a backend‐focused, serverless “smart study assistant” service, implemented as a Flask webhook that integrates with the LINE Messaging API and Google Gemini LLM.
- Users send text or images via LINE; the service retrieves fallback knowledge, filters for security, calls Gemini, and returns study guidance. It also logs interactions and can export reports to Excel.

##### High-Level Components
a. **LINE Users & LINE Messaging API**
- The entry point for user requests (text or image).
b. **Serverless Flask Webhook (api/webhook.py)**
- Deployed on Vercel (serverless function) or any Python host.
- Receives HTTP POSTs from LINE, parses events.
c. **GeminiResponder (src/gemini_responder.py)**
- Applies safety filters, constructs prompts, calls Google Gemini LLM via `google-generativeai` SDK.
d. **KnowledgeRetriever (src/knowledge_retriever.py)**
- Supplies fallback knowledge (e.g., local JSON, YAML, or embedded dataset) when Gemini alone isn’t enough.
e. **ReportManager (src/report_manager.py)**
- Logs every interaction (user message, AI response) to a local or ephemeral store.
- Optionally exports logs as Excel via pandas/openpyxl.
f. **External Services & Storage**
- Google Gemini LLM API (for AI reasoning)
- LINE Messaging API (user interface)
- Local “reports” directory or object store (for Excel exports)
- Vercel for deployment configuration (vercel.json)

##### Relationships & Data Flows
- User → LINE Messaging API → Webhook
- Webhook → (KnowledgeRetriever + GeminiResponder) → Google Gemini API
- GeminiResponder → Webhook → LINE Messaging API → User
- Webhook → ReportManager → Reports Dir/Excel
- Environment Variables (LINE_TOKEN, GEMINI_API_KEY) injected into serverless runtime

##### Architectural Patterns & Principles
- **Modular Monolith**: Each core function is a module (responder, retriever, reporter) called by a single HTTP entry point.
- **Single Responsibility**: Webhook handles HTTP; GeminiResponder handles AI calls & filtering; KnowledgeRetriever handles fallback data; ReportManager handles logging.
- **Serverless Friendly**: Designed to meet Vercel size/time constraints (no heavy dependencies, no persistent DB).
- **Security Layers**: Input filtering before prompt construction; length checks; sensitive content filtering.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Users and Services
    User["User"]:::external
    LINEapi["LINE Messaging API"]:::external
    GeminiAPI["Google Gemini LLM API"]:::external

    %% Serverless Function Boundary
    subgraph "Serverless Function (Vercel / Flask)"
        Webhook["Webhook Service (/api/webhook)"]:::module
        Retriever["KnowledgeRetriever"]:::module
        Responder["GeminiResponder"]:::module
        Reporter["ReportManager"]:::module
        Env[/"Env: LINE_TOKEN, GEMINI_API_KEY"/]:::annotation
        Env -.-> Webhook
    end

    %% Storage
    Reports["Reports Storage"]:::storage

    %% Project Files
    subgraph "Project Files"
        Vercel["vercel.json"]:::config
        Req["requirements.txt"]:::config
        Readme["README.md"]:::config
    end

    %% Data Flows
    User -->|"sends message"| LINEapi
    LINEapi -->|"HTTP POST"| Webhook
    Webhook -->|"/getFallbackKnowledge"| Retriever
    Webhook -->|"/constructPrompt"| Responder
    Responder -->|"SDK call"| GeminiAPI
    GeminiAPI -->|"response"| Responder
    Responder -->|"/reply Payload"| Webhook
    Webhook -->|"HTTP Response"| LINEapi
    Webhook -->|"logInteraction"| Reporter
    Reporter -->|"write Excel"| Reports

    %% Click Events
    click Webhook "https://github.com/trinity-syt-security/testlinetogemini/blob/main/api/webhook.py"
    click Responder "https://github.com/trinity-syt-security/testlinetogemini/blob/main/src/gemini_responder.py"
    click Retriever "https://github.com/trinity-syt-security/testlinetogemini/blob/main/src/knowledge_retriever.py"
    click Reporter "https://github.com/trinity-syt-security/testlinetogemini/blob/main/src/report_manager.py"
    click Vercel "https://github.com/trinity-syt-security/testlinetogemini/blob/main/vercel.json"
    click Req "https://github.com/trinity-syt-security/testlinetogemini/blob/main/requirements.txt"
    click Readme "https://github.com/trinity-syt-security/testlinetogemini/blob/main/README.md"

    %% Styles
    classDef module fill:#cce5ff,stroke:#004085,color:#004085
    classDef external fill:#d4edda,stroke:#155724,color:#155724
    classDef storage fill:#fff3cd,stroke:#856404,color:#856404
    classDef annotation fill:#e2e3e5,stroke:#d6d8db,color:#6c757d,stroke-dasharray:2 2
    classDef config fill:#f8f9fa,stroke:#6c757d,color:#343a40
```
