# isayanpal/roomie-finder architecture

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

- Interactive diagram: https://gitdiagram.com/isayanpal/roomie-finder
- Repository: https://github.com/isayanpal/roomie-finder

## Overview

##### Project Type and Purpose
- This is a full-stack roommate-matching web application built with Next.js (React + Server Components) and TypeScript.
- Purpose: allow students and professionals to create profiles, set preferences, find smart roommate matches, and chat in real time before committing.
- Key features: user onboarding (Google Sign-In via Supabase Auth), preferences management, match listing, in-app chat, and real-time notifications.

##### File Structure Analysis
- Top-level:
- next.config.ts, tailwind.config.ts, postcss.config.mjs, tsconfig.json – build and framework configs
- prisma/schema.prisma – database schema for Prisma ORM
- middleware.ts – Next.js middleware (e.g., auth guard)
- src/app – Next.js 13 (App Router) pages and server API routes under /api/*
- /api/* folders each contain route.ts files defining REST endpoints (chatHistory, matches, messages, preferences, profile, unreadMessages, user(s)).
- src/app/auth – Google OAuth callback and login page (page.tsx + route.ts)
- src/app/chat, /match, /preferences, /profile, /page.tsx – client-side pages using React components
- src/components – reusable UI building blocks
- custom – page-specific components (AuthForm, ChatHistory, MatchCard…)
- landingpage – marketing/landing page widgets
- ui – low-level UI primitives (Button, Input, Card…)
- magicui – specialized widgets (NumberTicker)
- src/lib – server utilities (Prisma client, helper utils)
- src/utils/supabase – Supabase client (browser) and server wrappers
- public & images – static assets

##### README Highlights
- Technology stack: Next.js, TypeScript, Supabase (PostgreSQL + Auth), Prisma ORM, Shadcn UI (Radix + Tailwind).
- Features emphasize Smart Matching, Profiles, Chat System, Real-Time Notifications, Google Sign-In.

##### Main Components
A. Frontend Layer
- Next.js App (React Server & Client Components)
- Pages: Landing, Auth, Profile, Preferences, Matches, Chat
- Components: UI primitives, custom widgets
- Supabase Client SDK for Auth & real-time features
B. Backend/API Layer
- Next.js API Routes (Route Handlers in src/app/api/*)
- middleware.ts for global tasks (auth verification, redirects)
- Prisma Client (src/lib/prisma.ts) ORM abstraction
- Supabase Server SDK (src/utils/supabase/server.ts) for DB and Auth management
C. Database & External Services
- Supabase PostgreSQL (user, profiles, preferences, matches, messages tables)
- Supabase Auth (Google OAuth provider)
- Vercel Hosting / CDN for static assets & serverless functions

##### Relationships & Data Flows
- User’s browser ←→ Next.js Frontend (pages/components)
- Login via Supabase Client → Google OAuth → Supabase Auth
- Frontend fetches data via built-in fetch() to Next.js API routes
- Next.js API Route → Prisma Client / Supabase Server SDK → PostgreSQL DB
- CRUD operations for Users, Profiles, Preferences, Matches, ChatHistory, Messages
- Real-Time Notifications
- Supabase real-time subscriptions (via WebSocket) or polling through API
- Frontend subscribed via Supabase Client -> display via NotificationBell component

##### Architectural Patterns & Principles
- Full-stack React SSR + Server Components (Next.js App Router)
- Layered separation: UI → API → ORM → Database
- Single codebase for front & back (monorepo pattern)
- Dependency injection of DB client via src/lib/prisma.ts
- Environment-configured external services (Supabase, Google OAuth)
- Component-driven UI architecture (custom vs. design-system primitives)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    U[("User Browser")]:::user

    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        NP["Landing Page"]:::frontend
        AP["Login Page"]:::frontend
        CB["OAuth Callback Route"]:::frontend
        PP["Profile Page"]:::frontend
        PrefP["Preferences Page"]:::frontend
        MP["Matches Page"]:::frontend
        CP["Chat Room Page"]:::frontend
        CHP["Chat History Page"]:::frontend
        UI["UI Library / Components"]:::frontend
        Custom["Custom Widgets"]:::frontend
        LandingWidgets["Landing Page Widgets"]:::frontend
        SBClient["Supabase Client SDK"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        MW["middleware.ts"]:::api
        CHAPI["chatHistory API"]:::api
        MAPI["matches API"]:::api
        MSGAPI["messages API"]:::api
        PREFAPI["preferences API"]:::api
        PROFAPI["profile API"]:::api
        UMSGAPI["unreadMessages API"]:::api
        USERAPI["user by ID API"]:::api
        USERSAPI["users list API"]:::api
    end

    %% Data Layer
    subgraph "Data & ORM"
        direction TB
        PC["Prisma Client"]:::data
        PS["Prisma Schema"]:::data
        SBServer["Supabase Server SDK"]:::data
    end

    %% External Services
    subgraph "External Services"
        direction TB
        DB["Supabase PostgreSQL"]:::external
        AuthSvc["Supabase Auth"]:::external
        Google["Google OAuth"]:::external
        Vercel["Vercel Hosting / CDN"]:::external
    end

    %% Relationships
    U --> NP
    U --> AP
    NP -->|"fetch()"| CHAPI
    NP -->|"fetch()"| MAPI
    NP -->|"fetch()"| MSGAPI
    NP -->|"fetch()"| PREFAPI
    NP -->|"fetch()"| PROFAPI
    NP -->|"fetch()"| UMSGAPI
    NP -->|"fetch()"| USERSAPI

    AP --> SBClient
    SBClient --> AuthSvc
    AuthSvc --> Google
    Google --> AuthSvc
    AuthSvc --> MW
    MW --> CHAPI
    MW --> MAPI
    MW --> MSGAPI
    MW --> PREFAPI
    MW --> PROFAPI
    MW --> UMSGAPI
    MW --> USERAPI
    MW --> USERSAPI

    CHAPI --> PC
    CHAPI --> SBServer
    MAPI --> PC
    MAPI --> SBServer
    MSGAPI --> PC
    MSGAPI --> SBServer
    PREFAPI --> PC
    PREFAPI --> SBServer
    PROFAPI --> PC
    PROFAPI --> SBServer
    UMSGAPI --> PC
    UMSGAPI --> SBServer
    USERAPI --> PC
    USERAPI --> SBServer
    USERSAPI --> PC
    USERSAPI --> SBServer

    PC --> PS
    PC --> DB
    SBServer --> DB

    SBClient -- "realtime subscriptions" --> SBServer
    SBClient -- "realtime subscriptions" --> DB

    %% Click Events - Presentation
    click NP "https://github.com/isayanpal/roomie-finder/blob/master/src/app/page.tsx"
    click AP "https://github.com/isayanpal/roomie-finder/blob/master/src/app/auth/page.tsx"
    click CB "https://github.com/isayanpal/roomie-finder/blob/master/src/app/auth/callback/route.ts"
    click PP "https://github.com/isayanpal/roomie-finder/blob/master/src/app/profile/page.tsx"
    click PrefP "https://github.com/isayanpal/roomie-finder/blob/master/src/app/preferences/page.tsx"
    click MP "https://github.com/isayanpal/roomie-finder/blob/master/src/app/match/page.tsx"
    click CP "https://github.com/isayanpal/roomie-finder/blob/master/src/app/chat/[id]/page.tsx"
    click CHP "https://github.com/isayanpal/roomie-finder/blob/master/src/app/chat/history/page.tsx"
    click UI "https://github.com/isayanpal/roomie-finder/tree/master/src/components/ui"
    click Custom "https://github.com/isayanpal/roomie-finder/tree/master/src/components/custom"
    click LandingWidgets "https://github.com/isayanpal/roomie-finder/tree/master/src/components/landingpage"
    click SBClient "https://github.com/isayanpal/roomie-finder/blob/master/src/utils/supabase/client.ts"

    %% Click Events - API
    click CHAPI "https://github.com/isayanpal/roomie-finder/blob/master/src/app/api/chatHistory/route.ts"
    click MAPI "https://github.com/isayanpal/roomie-finder/blob/master/src/app/api/matches/route.ts"
    click MSGAPI "https://github.com/isayanpal/roomie-finder/blob/master/src/app/api/messages/route.ts"
    click PREFAPI "https://github.com/isayanpal/roomie-finder/blob/master/src/app/api/preferences/route.ts"
    click PROFAPI "https://github.com/isayanpal/roomie-finder/blob/master/src/app/api/profile/route.ts"
    click UMSGAPI "https://github.com/isayanpal/roomie-finder/blob/master/src/app/api/unreadMessages/route.ts"
    click USERAPI "https://github.com/isayanpal/roomie-finder/blob/master/src/app/api/user/[id]/route.ts"
    click USERSAPI "https://github.com/isayanpal/roomie-finder/blob/master/src/app/api/users/route.ts"
    click MW "https://github.com/isayanpal/roomie-finder/blob/master/middleware.ts"

    %% Click Events - Data
    click PC "https://github.com/isayanpal/roomie-finder/blob/master/src/lib/prisma.ts"
    click PS "https://github.com/isayanpal/roomie-finder/blob/master/prisma/schema.prisma"
    click SBServer "https://github.com/isayanpal/roomie-finder/blob/master/src/utils/supabase/server.ts"

    %% Click Events - External (config files)
    click Vercel "https://github.com/isayanpal/roomie-finder/blob/master/next.config.ts"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#007bff,color:#000;
    classDef api fill:#d4edda,stroke:#28a745,color:#000;
    classDef data fill:#fff3cd,stroke:#ffc107,color:#000;
    classDef external fill:#f8d7da,stroke:#dc3545,color:#000;
    classDef user fill:#e2e3e5,stroke:#6c757d,color:#000;
```
