# naaimabk/feelya-sentiment-analysis-nlp-for-marketting architecture

> Architecture diagram of the GitHub repository naaimabk/feelya-sentiment-analysis-nlp-for-marketting, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/naaimabk/feelya-sentiment-analysis-nlp-for-marketting
- Repository: https://github.com/naaimabk/feelya-sentiment-analysis-nlp-for-marketting

## Overview

##### Project Type & Purpose
- Full-stack web application (SaaS) combining:
– A React-based frontend (SPA)
– A FastAPI backend serving REST endpoints
– ML/NLP pipelines (sentiment analysis, recommendations)
– Data storage (PostgreSQL via SQLAlchemy)
– Data ingestion (web scraping)

##### File Structure
- Top-level:
– main.py: FastAPI app entrypoint
– api/routes.py: HTTP endpoint definitions
– models/: DB connection & Pydantic schemas
– services/: Business logic (scraper, preprocessor, sentiment_analyzer, recommender)
– scripts/: One-off scripts (e.g., populate_database)
– frontend/frontend-app/: React code (SPA served by Vite)
– Dockerfile & docker-compose.yml: Containerization

##### Pull Architecture Insights from README
- Four main stages: Collect → Preprocess → Analyze → Recommend
- Tech stack: FastAPI, SQLAlchemy, Transformers (PyTorch), React, PostgreSQL
- External integrations: Web scraping Jumia & Hmizate

A. Client Layer
– Web Browser (User)
– React SPA (frontend-app)
B. API Layer
– FastAPI Application (main.py + api/routes.py)
C. Business-Logic Layer (services/)
– Scraper Service (services/scraper.py)
– Preprocessor Service (services/preprocessor.py)
– Sentiment Analyzer Service (services/sentiment_analyzer.py)
– Recommender Service (services/recommender.py)
D. Data Layer
– PostgreSQL Database (models/database.py via SQLAlchemy)
– Local feelya.db (SQLite for dev)
– scripts/populate_database.py
E. External Systems
– E-commerce sites (Jumia, Hmizate) for scraping
– Optional: Redis or Message Queue (for async tasks—future)

1. User → React SPA
2. React SPA → FastAPI (HTTP /api/v1/…)
3. FastAPI → Services Modules
- Review ingestion → Scraper (scripts run periodically)
- On /analyze-sentiment → Preprocessor → Sentiment Analyzer
- On /recommendations → Recommender (collaborative + content + sentiment)
4. Services → Database (read/write via SQLAlchemy)
5. Scraper → External E-commerce sites → persists raw reviews to DB
6. FastAPI → optional: Async task queue for long-running ML jobs

##### Architectural Patterns
- Layered architecture (Presentation → API → Domain Services → Data)
- Clear separation of concerns:
– “api/” purely HTTP routing
– “services/” purely business logic
– “models/” purely data models & DB connectivity
- Micro-services style modules inside a monolith
- Containerized deployment (Docker + docker-compose)

##### Technologies & Frameworks
- Frontend: React, Vite, Tailwind CSS, ESLint
- Backend: FastAPI, Uvicorn
- ORM: SQLAlchemy, Pydantic
- ML: Transformers (CamemBERT, AraBERT), PyTorch, scikit-learn
- DB: PostgreSQL (prod), SQLite (dev)
- Orchestration: Docker, docker-compose

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        User["Web Browser (User)"]:::client
        ReactSPA["React SPA (Vite, Tailwind, ESLint)"]:::client
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        FastAPIApp["FastAPI Application (Uvicorn)"]:::api
        APIRoutes["HTTP Endpoints (/api/v1...)"]:::api
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        direction TB
        ScraperSvc["Scraper Service"]:::service
        PreprocessorSvc["Preprocessor Service"]:::service
        SentimentSvc["Sentiment Analyzer Service"]:::service
        RecommenderSvc["Recommender Service"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        PostgresDB["PostgreSQL (SQLAlchemy)"]:::data
        SQLiteDB["SQLite Dev DB (feelya.db)"]:::data
        PopScript["populate_database.py"]:::data
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        EcomSites["E-commerce Sites\n(Jumia, Hmizate)"]:::external
    end

    %% Configurations
    subgraph "Configuration"
        direction TB
        DockerfileNode["Dockerfile"]:::config
        DockerComposeNode["docker-compose.yml"]:::config
        EnvConfig[".env / .env.example"]:::config
    end

    %% Connections
    User -->|"interacts with"| ReactSPA
    ReactSPA -->|"HTTP POST /analyze-sentiment\nGET /recommendations"| FastAPIApp
    FastAPIApp -->|"routes requests"| APIRoutes
    APIRoutes -->|"calls"| PreprocessorSvc
    APIRoutes -->|"calls"| SentimentSvc
    APIRoutes -->|"calls"| RecommenderSvc
    ScraperSvc -->|"scrapes reviews"| EcomSites
    ScraperSvc -->|"writes raw data"| PostgresDB
    PreprocessorSvc -->|"reads/writes"| PostgresDB
    SentimentSvc -->|"reads/writes"| PostgresDB
    RecommenderSvc -->|"reads/writes"| PostgresDB
    PopScript -->|"initializes data"| SQLiteDB
    FastAPIApp -->|"optional async tasks"| ScraperSvc

    %% Click Events
    click ReactSPA "https://github.com/naaimabk/feelya-sentiment-analysis-nlp-for-marketting/tree/main/frontend/frontend-app/"
    click FastAPIApp "https://github.com/naaimabk/feelya-sentiment-analysis-nlp-for-marketting/blob/main/main.py"
    click APIRoutes "https://github.com/naaimabk/feelya-sentiment-analysis-nlp-for-marketting/blob/main/api/routes.py"
    click PostgresDB "https://github.com/naaimabk/feelya-sentiment-analysis-nlp-for-marketting/blob/main/models/database.py"
    click ScraperSvc "https://github.com/naaimabk/feelya-sentiment-analysis-nlp-for-marketting/blob/main/services/scraper.py"
    click PreprocessorSvc "https://github.com/naaimabk/feelya-sentiment-analysis-nlp-for-marketting/blob/main/services/preprocessor.py"
    click SentimentSvc "https://github.com/naaimabk/feelya-sentiment-analysis-nlp-for-marketting/blob/main/services/sentiment_analyzer.py"
    click RecommenderSvc "https://github.com/naaimabk/feelya-sentiment-analysis-nlp-for-marketting/blob/main/services/recommender.py"
    click PopScript "https://github.com/naaimabk/feelya-sentiment-analysis-nlp-for-marketting/blob/main/scripts/populate_database.py"
    click SQLiteDB "https://github.com/naaimabk/feelya-sentiment-analysis-nlp-for-marketting/blob/main/feelya.db"
    click DockerfileNode "https://github.com/naaimabk/feelya-sentiment-analysis-nlp-for-marketting/tree/main/Dockerfile"
    click DockerComposeNode "https://github.com/naaimabk/feelya-sentiment-analysis-nlp-for-marketting/blob/main/docker-compose.yml"
    click EnvConfig "https://github.com/naaimabk/feelya-sentiment-analysis-nlp-for-marketting/blob/main/.env"

    %% Styles
    classDef client fill:#cce5ff,stroke:#004085,color:#004085
    classDef api fill:#d4edda,stroke:#155724,color:#155724
    classDef service fill:#fff3cd,stroke:#856404,color:#856404
    classDef data fill:#ffeeba,stroke:#856404,color:#856404
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef config fill:#f8d7da,stroke:#721c24,color:#721c24
```
