# xlr-aex/kyrria architecture

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

- Interactive diagram: https://gitdiagram.com/xlr-aex/kyrria
- Repository: https://github.com/xlr-aex/kyrria

## Overview

##### Project type and purpose
- KYRRIA is an open-source, Python/Streamlit application for RSS/Atom feed aggregation, enriched reading, local storage of articles, relational analysis (NER via Google Gemini), and interactive visualizations (charts + D3.js graphs).
- It targets end users who want to collect, browse, store, and analyze news/information streams.

##### File structure
- Top level:
- Kyrria.py – single entry point (Streamlit app)
- requirements.txt – Python dependencies
- .devcontainer/ – configuration for VS Code Dev Containers
- LICENSE, README.md
- No separate frontend/backend directories: the project follows the typical Streamlit pattern where the “frontend” UI and “backend” logic live in the same Python process.
- Storage layer (probably SQLite or local file caching) is invoked from within Kyrria.py or its imported modules.

##### README for additional insights
- Describes five major UI pages (Home, Feed Manager, RSS Reader, Nodes, Dashboard, Entities & Relations).
- Mentions external services & libraries: feed RSS/Atom, caching, local DB, D3.js, Google Gemini (NER), various plotting modules.
- Deployment target: local Python 3.12 or Streamlit Cloud.

##### Main components & how to reflect them
a. Main components
- Streamlit Application (Python runtime)
- UI Pages / Controllers (Home, Feed Manager, RSS Reader, Dashboard, Nodes, Entities & Relations)
- Feed Fetcher & Parser (RSS/Atom ingestion)
- Cache Layer (in-memory or file)
- Local Storage (SQLite or flat files)
- Analytics / NER Pipeline (calls to Google Gemini API)
- Visualization Modules (Plotting library for bar/treemap/timeline + D3.js graph)
- External Services: RSS/Atom sources, Google Gemini
- Deployment Environment: Local VM/Container or Streamlit Cloud

b. Relationships and interactions
1. User’s browser → HTTP request → Streamlit server
2. UI controller triggers Feed Fetcher → retrieves RSS/Atom feeds → forwards data to Cache
3. On “Save” action → Cache writes to Local Storage
4. Analytics page → reads from Local Storage → invokes NER pipeline → queries Google Gemini → returns entity/relation data
5. Visualization modules pull from Cache or Local Storage → render graphs (D3.js, matplotlib/plotly) → streamed back to UI

c. Architectural patterns or design principles
- Single-process, event-driven UI + business logic (Streamlit).
- Separation of concerns by page/controller within the single Python app.
- Layered architecture: Ingestion → Caching → Storage → Analysis → Visualization → Presentation.
- Use of external API for heavy tasks (NER), keeping core app lightweight.
- Stateless UI with stateful back-end components (cache, DB).

d. Relevant technologies, frameworks, or libraries
- Python 3.12, Streamlit
- feedparser or RSS libs
- SQLite (via Python’s sqlite3) or file-based cache
- Google Gemini APIs for NER
- D3.js for interactive graphs, plus Python plotting libs for other charts
- Devcontainer.json for uniform dev environment
- Streamlit Cloud for deployment

##### Detail without overthinking
- Logical components even if they run in one Python process.
- Every UI page’s dependencies.
- Role of caching vs. permanent storage.
- External NER service and RSS sources.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Presentation Layer"
        UI["Streamlit UI Pages\n(Home, Feed Manager,\nRSS Reader, Nodes,\nDashboard, Entities & Relations)"]:::presentation
    end

    subgraph "Ingestion Layer"
        FF["Feed Fetcher & Parser\n(RSS/Atom)"]:::ingestion
    end

    subgraph "Persistence Layer"
        Cache["Cache Layer\n(in-memory/file)"]:::persistence
        DB["Local Storage\n(SQLite/Files)"]:::persistence
    end

    subgraph "Analysis Layer"
        NER["NER Pipeline\n(Google Gemini API)"]:::analysis
    end

    subgraph "Visualization Layer"
        Viz["Visualization Modules\n(Plotly/Matplotlib,\nD3.js)"]:::visualization
    end

    subgraph "External Services"
        RSS["RSS/Atom Feeds"]:::external
        Gemini["Google Gemini API"]:::external
    end

    subgraph "Configuration & Documentation"
        Dev["Dev Container Config"]:::config
        Req["requirements.txt"]:::config
        Doc["README.md"]:::config
        Lic["LICENSE"]:::config
    end

    UI --> FF
    FF --> Cache
    FF --> RSS
    Cache --> DB
    UI --> DB
    UI --> Viz
    UI --> NER
    DB --> NER
    NER --> Gemini
    Cache --> Viz
    DB --> Viz

    click UI "https://github.com/xlr-aex/kyrria/blob/main/Kyrria.py"
    click FF "https://github.com/xlr-aex/kyrria/blob/main/Kyrria.py"
    click Cache "https://github.com/xlr-aex/kyrria/blob/main/Kyrria.py"
    click DB "https://github.com/xlr-aex/kyrria/blob/main/Kyrria.py"
    click NER "https://github.com/xlr-aex/kyrria/blob/main/Kyrria.py"
    click Viz "https://github.com/xlr-aex/kyrria/blob/main/Kyrria.py"
    click RSS "https://github.com/xlr-aex/kyrria/blob/main/Kyrria.py"
    click Gemini "https://github.com/xlr-aex/kyrria/blob/main/Kyrria.py"
    click Dev "https://github.com/xlr-aex/kyrria/blob/main/.devcontainer/devcontainer.json"
    click Req "https://github.com/xlr-aex/kyrria/blob/main/requirements.txt"
    click Doc "https://github.com/xlr-aex/kyrria/blob/main/README.md"
    click Lic "https://github.com/xlr-aex/kyrria/tree/main/LICENSE"

    classDef presentation fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef ingestion fill:#FFE5B4,stroke:#FF8C00,color:#8B4513;
    classDef persistence fill:#FFF5BA,stroke:#DAA520,color:#B8860B;
    classDef analysis fill:#D6EFD8,stroke:#228B22,color:#006400;
    classDef visualization fill:#E5D0FF,stroke:#800080,color:#4B0082;
    classDef external fill:#F0F0F0,stroke:#808080,color:#505050;
    classDef config fill:#F5F5F5,stroke:#A9A9A9,color:#696969;
```
