# nols05/sentinel architecture

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

- Interactive diagram: https://gitdiagram.com/nols05/sentinel
- Repository: https://github.com/nols05/sentinel

## Overview

##### Main Components
- Backend Service (Python)
– Contains the social media integration and sentiment analysis logic.
– Key modules include:
▫ api.py: likely routes incoming requests to specific functions.
▫ bluesky.py and reddit.py: handle fetching and processing data from respective social media platforms.
▫ sentiment_analysis folder: performs sentiment computations and model management (e.g., saveModel.py).
▫ utils modules: provide helper functions such as sorting and generating search text.
– Sample data is provided for testing or demonstration (the sample_data folder).

- Frontend Application (Next.js)
– Built using Next.js and React (evidenced by the extensive structure under frontend-next).
– Contains distinct modules:
▫ Auth (login, signup): for user authentication.
▫ Dashboard: displays various views such as data summaries, individual query results, and social media-specific sections (Reddit, possibly Bluesky mentions).
▫ Marketing: for landing pages or public-facing pages.
▫ API Endpoints: handles calls to authentication and triggers backend actions (for result fetching and status checking).
▫ Lib and hooks: abstract configuration, authentication session management, Prisma database integration (schema.prisma indicates use of Prisma as the ORM, likely tied to a SQL database).

- Database (Implicit)
– Indicated by the presence of a prisma schema in the frontend folder.
– Likely used for storing user credentials, sentiment analysis logs, or caching fetched results.

##### Relationships and Data Flow
- The Frontend communicates with the Backend through defined API endpoints.
- The user interacts with the Frontend through various pages (e.g., login, dashboards) and submits keywords.
- The Frontend invokes backend services (possibly over RESTful API calls) to:
▫ Trigger social media queries.
▫ Run sentiment analysis via the Python backend.
- The Backend fetches data from external social platforms (using the content in reddit.py and bluesky.py) and processes this data.
- The sentiment analysis module computes positive/negative scores and passes summaries back to the Frontend.
- The Database (managed via Prisma) is used to store persistent data such as user sessions, query histories, or analysis results.

##### Key Architectural Patterns and Technologies
- Separation of Concerns:
– Clear division between Frontend (presentation layer) and Backend (data processing and API integration).
- Microservices/Modular Architecture style:
– The backend is broken into modules (API routing, platform-specific integrations, sentiment analysis, utilities).
- API-Driven Communication:
– Frontend API endpoints act as a bridge between user actions and backend processing.
- Use of modern web frameworks:
– Frontend: Next.js, React, Tailwind CSS for the UI.
– Backend: Python with a modular design for handling different social media inputs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User(["User"]):::user

    subgraph "Frontend (Next.js)"
        FApp["Frontend Application"]:::frontend
        Auth["Authentication Module"]:::frontend
        Dash["Dashboard"]:::frontend
        Mkt["Marketing Pages"]:::frontend
        APIEnd["API Endpoints"]:::frontend
        UIComp["UI Components"]:::frontend
    end

    subgraph "Backend (Python Services)"
        APIH["API Handler (api.py)"]:::backend
        BSky["Bluesky Integration (bluesky.py)"]:::backend
        Rddt["Reddit Integration (reddit.py)"]:::backend
        SAnl["Sentiment Analysis Module"]:::backend
        Utils["Utility Functions"]:::backend
        SampleD["Sample Data"]:::backend
    end

    subgraph "External Services"
        EXBluesky["Bluesky API"]:::external
        EXReddit["Reddit API"]:::external
    end

    DB["Database (Prisma)"]:::database

    %% User interactions to Frontend
    User -->|"interacts"| FApp
    FApp -->|"navigates_to"| Auth
    FApp -->|"views"| Dash
    FApp -->|"accesses"| Mkt
    FApp -->|"calls"| APIEnd

    %% Frontend to Backend communication
    APIEnd -->|"requests"| APIH

    %% Backend internal communication
    APIH -->|"calls"| BSky
    APIH -->|"calls"| Rddt
    APIH -->|"runs"| SAnl
    APIH -->|"utilizes"| Utils
    APIH -->|"optionally_uses"| SampleD

    %% Backend to External Services
    BSky -->|"fetches_from"| EXBluesky
    Rddt -->|"fetches_from"| EXReddit

    %% Sentiment Analysis data flow
    SAnl -->|"analyzes_data_from"| BSky
    SAnl -->|"analyzes_data_from"| Rddt

    %% Backend response flow
    APIH -->|"returns_results_to"| APIEnd
    APIEnd -->|"displays_on"| Dash

    %% Database interactions
    FApp -->|"stores/reads"| DB
    APIH -->|"stores/reads"| DB

    %% Click Events
    click APIH "https://github.com/nols05/sentinel/blob/main/backend-python/api-py/api.py"
    click BSky "https://github.com/nols05/sentinel/blob/main/backend-python/api-py/bluesky.py"
    click Rddt "https://github.com/nols05/sentinel/blob/main/backend-python/api-py/reddit.py"
    click SAnl "https://github.com/nols05/sentinel/tree/main/backend-python/api-py/sentiment_analysis/"
    click SampleD "https://github.com/nols05/sentinel/tree/main/backend-python/api-py/sample_data/"
    click Utils "https://github.com/nols05/sentinel/tree/main/backend-python/api-py/utils/"
    click FApp "https://github.com/nols05/sentinel/tree/main/frontend-next/"
    click Auth "https://github.com/nols05/sentinel/tree/main/frontend-next/app/(auth)/"
    click Dash "https://github.com/nols05/sentinel/tree/main/frontend-next/app/(dashboard)/"
    click Mkt "https://github.com/nols05/sentinel/tree/main/frontend-next/app/(marketing)/"
    click APIEnd "https://github.com/nols05/sentinel/tree/main/frontend-next/app/api/"
    click UIComp "https://github.com/nols05/sentinel/tree/main/frontend-next/components/ui/"
    click DB "https://github.com/nols05/sentinel/blob/main/frontend-next/prisma/schema.prisma"

    %% Styles
    classDef frontend fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef backend fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef external fill:#FFF9C4,stroke:#F9A825,stroke-width:2px;
    classDef database fill:#FFCCBC,stroke:#D84315,stroke-width:2px;
    classDef user fill:#E1BEE7,stroke:#6A1B9A,stroke-width:2px;
```
