mirror of https://github.com/yusufipk/distromatch.git synced 2026-09-11 10:46:07 +00:00

Files

T

yusufipk 3498832ec8 Add detailed documentation for DistroMatch web application

Provide an overview of the DistroMatch application, its user preferences, system architecture including frontend and backend components, scoring system, data layer, and external dependencies.

Replit-Commit-Author: Agent
Replit-Commit-Session-Id: e522d728-b28a-437f-b576-83935afe7ea0
Replit-Commit-Checkpoint-Type: full_checkpoint
Replit-Commit-Event-Id: 9530afaf-358f-4eb6-b53c-b4857305f409
Replit-Commit-Screenshot-Url: https://storage.googleapis.com/screenshot-production-us-central1/55e426a8-5a2b-421b-8bd4-30481ae0063b/e522d728-b28a-437f-b576-83935afe7ea0/Ps87hd1
Replit-Helium-Checkpoint-Created: true

2025-12-17 14:11:47 +00:00

3.2 KiB

Raw Blame History

DistroMatch

Overview

DistroMatch is a "Tinder for Linux Distros" web application that helps users find their perfect Linux distribution through a swipe-based discovery experience. Users swipe through desktop environment cards and answer preference questions, then receive personalized distro recommendations with witty roasts based on their choices.

The app features a cinematic, desktop-first UI with landscape-oriented cards, dynamic gradient backgrounds, and smooth Framer Motion animations. Content is presented in Turkish.

User Preferences

Preferred communication style: Simple, everyday language.

System Architecture

Frontend Architecture

Framework: React 18 with TypeScript
Routing: Wouter (lightweight client-side routing)
State Management: React Query for server state, local useState for UI state
Animations: Framer Motion for swipe gestures and transitions
Styling: Tailwind CSS with custom design tokens in CSS variables
UI Components: shadcn/ui (Radix UI primitives with custom styling)

Component Structure

The app uses a card-stack interaction pattern:

DistroMatch - Main orchestrator managing stages (DE selection → questions → results)
CardStack / DECard / QuestionCard - Swipeable card components with gesture handling
ResultsScreen - Displays scored distro recommendations with roast messages
DynamicBackground - Reactive gradient background that changes with card colors

Scoring System

Located in client/src/lib/scoring.ts:

Calculates distro compatibility based on user preferences
Considers: liked/disliked desktop environments, NVIDIA support, RAM requirements, gaming focus, privacy needs, rolling release preference
Returns ranked list of distributions with match reasons

Data Layer

Static JSON data in client/src/data/distros.json for distro definitions
TypeScript interfaces in client/src/data/distros.ts for type safety
Roast templates in client/src/data/roasts.ts with conditional message selection

Backend Architecture

Runtime: Node.js with Express
Build Tool: Vite for frontend, esbuild for server bundling
API Pattern: RESTful routes prefixed with /api
Storage Interface: Abstracted via IStorage interface (currently in-memory, database-ready)

Database Schema

Configured with Drizzle ORM for PostgreSQL:

users table with id, username, password fields
Schema defined in shared/schema.ts with Zod validation via drizzle-zod
Database URL expected via DATABASE_URL environment variable

External Dependencies

Core Services

PostgreSQL: Database (requires DATABASE_URL environment variable)
Google Fonts: Inter and Space Grotesk typefaces loaded via CDN

Key NPM Packages

drizzle-orm + drizzle-kit: Database ORM and migrations
@tanstack/react-query: Async state management
framer-motion: Animation library for swipe interactions
wouter: Client-side routing
zod: Runtime type validation
@radix-ui/*: Accessible UI primitives
tailwindcss: Utility-first CSS framework

Development Tools

tsx: TypeScript execution for development
vite: Frontend build and HMR
Replit-specific plugins for error overlay and dev tooling

3.2 KiB Raw Blame History