How aakashpathak1/connectle works
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.