# bassel20/multilingual_review_analyzer architecture

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

- Interactive diagram: https://gitdiagram.com/bassel20/multilingual_review_analyzer
- Repository: https://github.com/bassel20/multilingual_review_analyzer

## Overview

##### Project Type & Purpose
- Full-stack web application for multilingual feedback collection, translation, and sentiment analysis.
- Frontend: React SPA with Recharts for data visualization.
- Backend: Python FastAPI providing RESTful endpoints.
- Persistence: PostgreSQL via SQLAlchemy ORM.
- External AI Service: Google Gemini Flash for language detection, translation, and sentiment.

##### File Structure
- Top-level directories:
– backend/ – FastAPI application (main.py, crud.py, models.py, schemas.py, gemini_client.py, database.py, services.py).
– frontend/ – React application (public/index.html, src/components, src/services/api.js).
- Deployment files:
– docker-compose.yml orchestrates three containers: frontend, backend, database.
– Dockerfile in each service for container builds.
- Architectural cues:
– Layered separation (presentation, application logic, persistence)
– Clear API boundary between frontend and backend
– Dedicated module for external-service integration (gemini_client).

##### README for Additional Insights
- Detailed API routes (/api/feedback, /api/translate, /api/stats, /health).
- Data model: feedback table schema with text, language code, translation, sentiment, timestamp.
- Environment variables and build/run instructions.

##### Main Components & Their Roles
a. User Browser: Hosts the React SPA; interacts via HTTP.
b. Frontend Container: Serves static assets or runs dev server on port 3000; contains UI components (Dashboard, FeedbackForm, FeedbackList) and API client (Axios).
c. Backend Container: FastAPI app on port 8000; modules include:
– API router (main.py)
– Database layer (database.py, models.py, crud.py)
– Gemini integration (gemini_client.py, services.py)
– Validation schemas (schemas.py)
d. Database Container: PostgreSQL on port 5432; stores feedback records.
e. External Service: Google Gemini API (HTTPS) for language detection, translation, and sentiment analysis.

##### Relationships & Data Flow
1. Feedback submission:
User → Frontend (POST /api/feedback) → Backend
→ gemini_client calls Google Gemini → receives language/translation/sentiment
→ crud persists record in PostgreSQL
→ Backend responds → Frontend updates UI.
2. Analytics retrieval:
Frontend (GET /api/stats) → Backend aggregates via SQLAlchemy → PostgreSQL → returns counts → Recharts renders charts.
3. Feedback listing/filtering:
Frontend (GET /api/feedback?language=…&sentiment=…) → Backend → Database → UI.
4. Health checks:
Monitoring system calls GET /health → Backend checks DB and Gemini connectivity → reports status.

##### Architectural Patterns & Principles
- Three-tier architecture (Presentation, Application, Data).
- Separation of concerns: UI, API, persistence, external-service client.
- Containerization via Docker Compose for environment parity.
- Stateless services: each HTTP request is handled independently.
- Abstraction of external dependencies behind a client module.

##### Essential Elements
- Clear labels: container names, ports (3000, 8000, 5432), service names.
- Optional: monitoring/health-check flow to show system observability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Monitoring
    User["User Browser"]:::ui
    Monitor["Monitoring System"]:::monitor

    %% Docker Compose Network
    subgraph "Docker Compose Network"
        direction TB
        subgraph "Frontend Container" 
            direction TB
            FE_HTML["index.html"]:::ui
            FE_Index["index.js"]:::ui
            FE_App["App.js"]:::ui
            FE_Dashboard["Dashboard.js"]:::ui
            FE_Form["FeedbackForm.js"]:::ui
            FE_List["FeedbackList.js"]:::ui
            FE_API["api.js"]:::ui
        end
        subgraph "Backend Container"
            direction TB
            BE_Main["main.py"]:::backend
            BE_CRUD["crud.py"]:::backend
            BE_DBConfig["database.py"]:::backend
            BE_Models["models.py"]:::backend
            BE_Schemas["schemas.py"]:::backend
            BE_GeminiClient["gemini_client.py"]:::backend
            BE_Services["services.py"]:::backend
            BE_Reqs["requirements.txt"]:::backend
            BE_Dockerfile["Dockerfile"]:::backend
            Config["Env Variables"]:::config
        end
        subgraph "Database Container"
            direction TB
            DB[(PostgreSQL 5432)]:::db
        end
    end

    ExternalAI["Google Gemini API"]:::external

    %% User flows
    User -->|HTTP POST /api/feedback| FE_Form
    FE_Form --> FE_API
    FE_List --> FE_API
    FE_Dashboard --> FE_API
    FE_API -->|HTTP POST /api/feedback| BE_Main
    FE_API -->|HTTP GET /api/stats| BE_Main
    FE_API -->|HTTP GET /api/feedback| BE_Main

    %% Backend internal
    BE_Main --> BE_Schemas
    BE_Main --> BE_CRUD
    BE_Main --> BE_Services
    BE_Services --> BE_GeminiClient
    BE_Services --> BE_CRUD
    BE_CRUD --> BE_DBConfig
    BE_DBConfig --> DB
    BE_CRUD --> BE_Models
    BE_Main --> DB

    %% External calls
    BE_GeminiClient -->|HTTPS API Calls| ExternalAI

    %% Responses
    BE_Main -->|Response JSON| FE_API
    FE_API -->|Updates UI| FE_Dashboard
    FE_API -->|Updates UI| FE_List

    %% Health check
    Monitor -->|HTTP GET /health| BE_Main
    BE_Main --> DB
    BE_Main --> ExternalAI

    %% Click events
    click FE_HTML "https://github.com/bassel20/multilingual_review_analyzer/blob/master/frontend/public/index.html"
    click FE_Index "https://github.com/bassel20/multilingual_review_analyzer/blob/master/frontend/src/index.js"
    click FE_App "https://github.com/bassel20/multilingual_review_analyzer/blob/master/frontend/src/App.js"
    click FE_Dashboard "https://github.com/bassel20/multilingual_review_analyzer/blob/master/frontend/src/components/Dashboard.js"
    click FE_Form "https://github.com/bassel20/multilingual_review_analyzer/blob/master/frontend/src/components/FeedbackForm.js"
    click FE_List "https://github.com/bassel20/multilingual_review_analyzer/blob/master/frontend/src/components/FeedbackList.js"
    click FE_API "https://github.com/bassel20/multilingual_review_analyzer/blob/master/frontend/src/services/api.js"
    click BE_Main "https://github.com/bassel20/multilingual_review_analyzer/blob/master/backend/app/main.py"
    click BE_CRUD "https://github.com/bassel20/multilingual_review_analyzer/blob/master/backend/app/crud.py"
    click BE_DBConfig "https://github.com/bassel20/multilingual_review_analyzer/blob/master/backend/app/database.py"
    click BE_Models "https://github.com/bassel20/multilingual_review_analyzer/blob/master/backend/app/models.py"
    click BE_Schemas "https://github.com/bassel20/multilingual_review_analyzer/blob/master/backend/app/schemas.py"
    click BE_GeminiClient "https://github.com/bassel20/multilingual_review_analyzer/blob/master/backend/app/gemini_client.py"
    click BE_Services "https://github.com/bassel20/multilingual_review_analyzer/blob/master/backend/app/services.py"
    click BE_Reqs "https://github.com/bassel20/multilingual_review_analyzer/blob/master/backend/requirements.txt"
    click BE_Dockerfile "https://github.com/bassel20/multilingual_review_analyzer/tree/master/backend/Dockerfile"
    click DB "https://github.com/bassel20/multilingual_review_analyzer/blob/master/docker-compose.yml"

    %% Styles
    classDef ui fill:#DCEEFB,stroke:#4D8EF7,color:#0B4278
    classDef backend fill:#E6F4EA,stroke:#34A853,color:#0A5136
    classDef db fill:#FFF4E5,stroke:#FBBC05,color:#A36D00
    classDef external fill:#F3E8FD,stroke:#A142F4,color:#4A0868
    classDef config fill:#F0F0F0,stroke:#999999,color:#333333
    classDef monitor fill:#FFEFEF,stroke:#EA4335,color:#8B1A1A
```
