# ecyx00/summaryfinance architecture

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

- Interactive diagram: https://gitdiagram.com/ecyx00/summaryfinance
- Repository: https://github.com/ecyx00/summaryfinance

## Overview

##### Project Type and Purpose
- This is a full-stack news-aggregation and summarization system.
- Components:
- Spring Boot backend (Java 17) for news collection, scheduling, persistence, and REST/SSE APIs
- Python AI Service (FastAPI) for content scraping, AI analysis, and summary generation
- Static frontend (HTML/CSS/JS) for displaying results
- PostgreSQL database for persistence
- External news APIs (NYTimes, Guardian)

##### File Structure
- Top-level directories:
- backend/ (Maven-based Spring Boot code under src/main/java)
- ai_service/ (Python FastAPI service under src/)
- frontend/ (static files: index.html, JS, CSS)
- docs/ (API docs)
- Notice MVC-style layering in backend: controllers, services, repositories, entities, config, scheduler, clients
- Python AI service modules: core (config, logging), db (models, CRUD), processing (scraper, analyzer, preparer, sender), main entry point
- Tests exist for both backend and ai_service

##### README Insights
- Two main components described under “Proje Yapısı”
- Tech stack listed: Java/Spring Boot, Python/FastAPI, PostgreSQL, newspaper3k
- Startup instructions hint at how the pieces run and communicate (FastAPI on uvicorn, Spring on port 8080)

##### Main Components & Interactions
- Frontend (Static Web UI)
- Backend (Spring Boot service)
- AI Microservice (FastAPI Python service)
- Database (PostgreSQL)
- External News APIs (NYTimes, Guardian)
b. Relationships & data flows:
1. Scheduler (backend) periodically invokes NewsSourceClient → fetches articles
2. Backend persists raw News entities → downstream triggers AI processing
3. Backend calls AI Service HTTP endpoint to analyze and summarize
4. AI Service scrapes content, runs Gemini analyzer, stores results, and notifies backend (or writes back to DB)
5. Backend merges AI results into database via ProcessedAiResultsService → persisted Summary entities
6. Frontend pulls or subscribes (SSE) to backend endpoints (SummaryController, SseNotificationController) to display updated summaries
c. Architectural patterns & design principles:
- Microservice separation (backend vs AI)
- Layered architecture in backend (Controller → Service → Repository → DB)
- Configuration/externalization (.env and application.properties)
- Asynchronous scheduling via Spring’s @Scheduled jobs
- RESTful and SSE for push notifications
d. Key technologies to annotate:
- Spring Boot, Maven, Java 17
- FastAPI, Uvicorn, Python 3.x, newspaper3k
- PostgreSQL
- HTTP/REST, Server-Sent Events

##### Essential Details to Capture
- Scheduling flow (NewsScheduler)
- Where config files (.env, application.properties) feed into respective services

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend"
        UI["index.html"]:::frontend
        CSS["style.css"]:::frontend
        JS["script.js"]:::frontend
    end

    %% Backend Service
    subgraph "Backend Service"
        Main["SummaryfinanceApplication"]:::backend
        subgraph "Configuration"
            AppProps["application-prod.properties"]:::backend
            AppExample["application.properties.example"]:::backend
            ScheduleConf["SchedulingConfig"]:::backend
        end
        subgraph "Scheduler"
            Scheduler["NewsScheduler"]:::backend
        end
        subgraph "Clients"
            NSClient["NewsSourceClient"]:::backend
            NYTimesClient["NYTimesClient"]:::backend
            GuardianClient["GuardianClient"]:::backend
        end
        subgraph "Controllers"
            NewsCtrl["NewsController"]:::backend
            SummaryCtrl["SummaryController"]:::backend
            SseCtrl["SseNotificationController"]:::backend
        end
        subgraph "Services"
            NewsSvc["NewsService"]:::backend
            SummarySvc["SummaryService"]:::backend
            ProcessedSvc["ProcessedAiResultsService"]:::backend
        end
    end

    %% AI Microservice
    subgraph "AI Microservice"
        MainAI["main.py"]:::ai
        subgraph "Config & Core"
            AIConfig["config.py"]:::ai
            LoggingCfg["logging_config.py"]:::ai
        end
        subgraph "DB Access"
            DbMod["database.py"]:::ai
            Models["models.py"]:::ai
            Crud["crud.py"]:::ai
        end
        subgraph "Processing Pipeline"
            Scraper["content_scraper.py"]:::ai
            Analyzer["gemini_analyzer.py"]:::ai
            Preparer["data_preparer.py"]:::ai
            Sender["result_sender.py"]:::ai
        end
    end

    %% Database
    DB["PostgreSQL"]:::db

    %% External APIs
    subgraph "External News APIs"
        API1["NYTimes API"]:::external
        API2["Guardian API"]:::external
    end

    %% Data Flows
    API1 -->|GET articles| Scheduler
    API2 -->|GET articles| Scheduler
    Scheduler -->|calls NewsSourceClient| NSClient
    NSClient -->|delegates to| NYTimesClient
    NSClient -->|delegates to| GuardianClient
    Scheduler -->|write News entities| DB
    NewsSvc -->|write News entities| DB
    SummarySvc -->|HTTP POST /analyze| MainAI
    MainAI -->|invoke scraper| Scraper
    Scraper -->|analysis| Analyzer
    Analyzer -->|prepare data| Preparer
    Preparer -->|send results| Sender
    Sender -->|write processed results| DB
    UI -->|GET /summaries| SummaryCtrl
    UI -->|SSE subscribe| SseCtrl
    NewsCtrl -->|uses| NewsSvc
    SummaryCtrl -->|uses| SummarySvc
    ProcessedSvc -->|reads results| DB

    %% Click Events
    click UI "https://github.com/ecyx00/summaryfinance/blob/main/frontend/index.html"
    click CSS "https://github.com/ecyx00/summaryfinance/blob/main/frontend/css/style.css"
    click JS "https://github.com/ecyx00/summaryfinance/blob/main/frontend/js/script.js"
    click Main "https://github.com/ecyx00/summaryfinance/blob/main/backend/src/main/java/com/example/summaryfinance/SummaryfinanceApplication.java"
    click ScheduleConf "https://github.com/ecyx00/summaryfinance/blob/main/backend/src/main/java/com/example/summaryfinance/config/SchedulingConfig.java"
    click AppProps "https://github.com/ecyx00/summaryfinance/blob/main/backend/src/main/resources/application-prod.properties"
    click AppExample "https://github.com/ecyx00/summaryfinance/blob/main/backend/src/main/resources/application.properties.example"
    click Scheduler "https://github.com/ecyx00/summaryfinance/blob/main/backend/src/main/java/com/example/summaryfinance/scheduler/NewsScheduler.java"
    click NYTimesClient "https://github.com/ecyx00/summaryfinance/blob/main/backend/src/main/java/com/example/summaryfinance/client/NYTimesClient.java"
    click GuardianClient "https://github.com/ecyx00/summaryfinance/blob/main/backend/src/main/java/com/example/summaryfinance/client/GuardianClient.java"
    click NSClient "https://github.com/ecyx00/summaryfinance/blob/main/backend/src/main/java/com/example/summaryfinance/client/NewsSourceClient.java"
    click NewsCtrl "https://github.com/ecyx00/summaryfinance/blob/main/backend/src/main/java/com/example/summaryfinance/controller/NewsController.java"
    click SummaryCtrl "https://github.com/ecyx00/summaryfinance/blob/main/backend/src/main/java/com/example/summaryfinance/controller/SummaryController.java"
    click SseCtrl "https://github.com/ecyx00/summaryfinance/blob/main/backend/src/main/java/com/example/summaryfinance/controller/SseNotificationController.java"
    click MainAI "https://github.com/ecyx00/summaryfinance/blob/main/ai_service/src/main.py"
    click AIConfig "https://github.com/ecyx00/summaryfinance/blob/main/ai_service/src/core/config.py"
    click LoggingCfg "https://github.com/ecyx00/summaryfinance/blob/main/ai_service/src/core/logging_config.py"
    click DbMod "https://github.com/ecyx00/summaryfinance/blob/main/ai_service/src/db/database.py"
    click Models "https://github.com/ecyx00/summaryfinance/blob/main/ai_service/src/db/models.py"
    click Crud "https://github.com/ecyx00/summaryfinance/blob/main/ai_service/src/db/crud.py"
    click Scraper "https://github.com/ecyx00/summaryfinance/blob/main/ai_service/src/processing/content_scraper.py"
    click Analyzer "https://github.com/ecyx00/summaryfinance/blob/main/ai_service/src/processing/gemini_analyzer.py"
    click Preparer "https://github.com/ecyx00/summaryfinance/blob/main/ai_service/src/processing/data_preparer.py"
    click Sender "https://github.com/ecyx00/summaryfinance/blob/main/ai_service/src/processing/result_sender.py"

    %% Styles
    classDef frontend fill:#E3F2FD,stroke:#1E88E5,color:#0D47A1;
    classDef backend fill:#E8F5E9,stroke:#43A047,color:#1B5E20;
    classDef ai fill:#FFF3E0,stroke:#FB8C00,color:#E65100;
    classDef db fill:#F3E5F5,stroke:#8E24AA,color:#4A148C;
    classDef external fill:#ECEFF1,stroke:#607D8B,color:#263238;
```
