# aakashpathak1/connectle architecture

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

- Interactive diagram: https://gitdiagram.com/aakashpathak1/connectle
- Repository: https://github.com/aakashpathak1/connectle

## Overview

##### Main Components
- Frontend Client – Built with Next.js (React with TypeScript) and styled with Tailwind CSS and Framer Motion. It handles user interactions, game visualization, chain building, error displays, and analytics tracking.
- Backend API – A Flask-based RESTful API that processes game logic, handles HTTP requests, manages rate limiting, caching, logging, and error responses.
- Supabase Database – Stores daily puzzles, game histories, and user statistics, serving as the persistent storage layer for the game data.
- HuggingFace NLP Service – A FastAPI-powered service that integrates a pre-trained Sentence Transformer model for computing semantic similarity between words. It is responsible for powering the NLP hints, similarity scoring, and word embedding retrieval.
- Utility Scripts – Scripts (in the API directory) for puzzle generation, cron jobs, and other maintenance tasks for managing and updating game data.

##### Component Interactions and Relationships
- Frontend ↔ Backend: The frontend communicates with the Flask-based backend via RESTful API endpoints. The API serves requests for gameplay data (word pairs, validation results, and hint requests) and also passes responses back to the client.
- Backend ↔ Database: The backend connects to the Supabase PostgreSQL database to query, store, and update persistent game data (daily puzzles, game history, statistics).
- Backend/Frontend ↔ HuggingFace NLP Service: When a word needs semantic similarity calculation or NLP-powered hints, the API (or even sometimes directly from the frontend via a configured endpoint) reaches out to the HuggingFace FastAPI service. This service uses a model like Sentence-Transformers (all-MiniLM-L6-v2) to compute and return similarity scores and embeddings.
- Utility Scripts ↔ Backend/Database: Utility scripts run as cron jobs or manual maintenance commands to generate daily puzzles and process word pair data.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The architecture divides responsibilities clearly among frontend (presentation), backend (business logic and API), NLP service (specialized semantic processing), and database (persistent storage).
- Microservices/Modular Design: While not fully microservices, the use of a separate FastAPI service for NLP tasks demonstrates a microservice-like approach for heavy or specialized processing.
- Scalability & Extensibility: The system is designed to allow future expansion such as optional user accounts, more enhanced caching (using Redis as mentioned), and external analytics integration.
- DevOps and CI/CD: Deployment strategies include Vercel for the frontend and serverless backend deployment, GitHub Actions for CI/CD, and Docker for local development.

##### Specific Technologies and Frameworks
- Frontend: Next.js, React, TypeScript, Tailwind CSS, Framer Motion, Vercel Analytics.
- Backend: Python, Flask, Flask-Limiter, logging, rate limiting libraries.
- NLP Service: FastAPI, HuggingFace Transformers, Sentence Transformers, and supplementary libraries like NLTK, NumPy.
- Database: Supabase (PostgreSQL) and optionally Redis for caching.
- Utility Scripts: Python scripts for cron jobs and puzzle generation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        FE["Frontend Client (Next.js, React, Tailwind CSS, Framer Motion)"]:::frontend
    end

    %% Backend & NLP Layer
    subgraph "Backend Layer"
        BE["Backend API (Flask)"]:::backend
        NLP["HuggingFace NLP Service (FastAPI, Sentence-Transformers all-MiniLM-L6-v2)"]:::nlp
    end

    %% Database Layer
    subgraph "Database & Storage"
        DB["Supabase Database (PostgreSQL)"]:::database
    end

    %% Utility Scripts
    subgraph "Utility Scripts"
        UT["Utility Scripts (Cron jobs, Puzzle Generation)"]:::utility
    end

    %% Deployment & Operations
    subgraph "Deployment & Operations"
        VERCEL["Vercel"]:::deployment
        GHACTIONS["GitHub Actions"]:::deployment
        DOCKER["Docker"]:::deployment
    end

    %% Connections
    FE -->|"API_Requests(game_logic,word_validation)"| BE
    BE -->|"Data_Storage&Retrieval"| DB
    BE -->|"Semantic_Similarity/NLP_Requests"| NLP
    UT -->|"Maintenance_Tasks"| BE
    UT -->|"Updates/Puzzle_Generation"| DB

    VERCEL -->|"Deploys_Frontend"| FE
    GHACTIONS -->|"CI/CD_for_Backend"| BE
    GHACTIONS -->|"CI/CD_for_Utility"| UT
    DOCKER -->|"Local_Development"| BE

    %% Click Events
    click FE "https://github.com/aakashpathak1/connectle/tree/main/frontend/"
    click BE "https://github.com/aakashpathak1/connectle/blob/main/api/app/routes.py"
    click DB "https://github.com/aakashpathak1/connectle/tree/main/supabase/migrations/"
    click NLP "https://github.com/aakashpathak1/connectle/blob/main/api/app/services/hint_service.py"
    click UT "https://github.com/aakashpathak1/connectle/tree/main/api/scripts/"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef backend fill:#A9DFBF,stroke:#28B463,stroke-width:2px;
    classDef database fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef nlp fill:#F5B7B1,stroke:#E74C3C,stroke-width:2px;
    classDef utility fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef deployment fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
```
