# rafapolo/sumaria architecture

> Architecture diagram of the GitHub repository rafapolo/sumaria, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rafapolo/sumaria
- Repository: https://github.com/rafapolo/sumaria

## Overview

##### Project type and purpose
- This is a lightweight command-line application (“SumarIA”) for fetching YouTube video transcripts and generating summaries using a local open-source LLM.
- It’s an open-source tool or CLI utility rather than a full-stack web app or microservice suite.

##### File structure
- Top-level:
– src/
- sumaria.py – the CLI entry point
- transcript_fetcher.py – encapsulates YouTube Transcript API calls
- summarizer.py – encapsulates prompt-construction, chunking logic, and LLM calls
– cached/ – persistent storage of raw transcripts and summary outputs
– requirements.txt – Python dependencies (requests, youtube-transcript-api)
- No “frontend/backend” split; modules follow a simple pipeline pattern.

##### README for architecture hints
- Describes three main components: entry point, fetcher, summarizer
- External dependencies: YouTube Transcript API, a local Ollama LLM server (HTTP on localhost)
- Caching layer to avoid repeated fetches

a. Main components
1. CLI Layer (sumaria.py)
2. Transcript Fetcher Module
3. Summarizer Module
4. Cache / File System (cached/)
5. External Services:
– YouTube Transcript API
– Local LLM Service (Ollama HTTP server)
b. Relationships & data flow
1. User invokes CLI → sumaria.py parses video ID
2. sumaria.py calls Transcript Fetcher → checks cache → if miss, invokes YouTube API → writes transcript.txt to cached/<video_id>/
3. sumaria.py calls Summarizer → reads transcript.txt → splits into semantic chunks → for each chunk, sends HTTP request to local LLM service → receives chunk summary
4. Aggregator collates chunk summaries → writes summary.md in cached/<video_id>/
5. sumaria.py logs results to console
c. Architectural patterns & principles
- Pipeline pattern: sequential processing (fetch → transform → output)
- Single-responsibility modules (fetcher vs. summarizer)
- Caching for idempotency and performance
- Externalized prompts and chunking logic for maintainability
d. Key technologies & libraries
- Python 3.x
- requests (HTTP client)
- youtube-transcript-api
- ollama (local LLM serve via HTTP)
- local file I/O for caching

##### Detail without over-splitting
- Every module boundary and cache interaction
- Avoid decomposing internal functions too deeply—focus on inter-module boundaries

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Modules
    CLI["CLI Layer<br/>(sumaria.py)"]:::code
    Fetcher["TranscriptFetcher Module<br/>(transcript_fetcher.py)"]:::code
    Summarizer["Summarizer Module<br/>(summarizer.py)<br/>- splits into 2000-char chunks<br/>- constructs prompts"]:::code

    %% Storage and Dependencies
    Cache["Cache / File System<br/>(cached/)"]:::storage
    Requirements["requirements.txt"]:::config

    %% External Services
    YouTubeAPI["YouTube Transcript API"]:::external
    LLM["Local LLM Service<br/>(Ollama HTTP)"]:::external

    %% Data Flow
    CLI -->|invokes with video ID| Fetcher
    Fetcher -->|check cache| Cache
    Fetcher -->|HTTP GET transcript| YouTubeAPI
    YouTubeAPI -->|returns raw transcript| Fetcher
    Fetcher -->|write transcript.txt| Cache
    CLI -->|calls summarizer| Summarizer
    Summarizer -->|read transcript.txt| Cache
    Summarizer -->|HTTP POST each chunk| LLM
    LLM -->|returns chunk summary| Summarizer
    Summarizer -->|aggregate & write summary.md| Cache
    Summarizer -->|return full summary| CLI
    Requirements -.->|dependencies| CLI

    %% Click Events
    click CLI "https://github.com/rafapolo/sumaria/blob/main/src/sumaria.py"
    click Fetcher "https://github.com/rafapolo/sumaria/blob/main/src/transcript_fetcher.py"
    click Summarizer "https://github.com/rafapolo/sumaria/blob/main/src/summarizer.py"
    click Cache "https://github.com/rafapolo/sumaria/tree/main/cached/"
    click Requirements "https://github.com/rafapolo/sumaria/blob/main/requirements.txt"

    %% Styles
    classDef code fill:#a3d5ff,stroke:#333,stroke-width:1px;
    classDef storage fill:#fff2a8,stroke:#333,stroke-width:1px;
    classDef external fill:#c2f0c2,stroke:#333,stroke-width:1px;
    classDef config fill:#f4cccc,stroke:#333,stroke-width:1px;
```
