# denniswoods383/karu-teens-social-platform architecture

> Architecture diagram of the GitHub repository denniswoods383/karu-teens-social-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/denniswoods383/karu-teens-social-platform
- Repository: https://github.com/denniswoods383/karu-teens-social-platform

## Overview

##### Project type and purpose
- This is a full-stack social media web application built with Next.js (frontend and serverless API layer) and Supabase (backend as a service offering Postgres, Auth, Realtime, and storage).
- Its core purpose is to allow university students to register/log in, manage profiles, create and consume posts, chat in real time, and receive notifications, with AI-powered tools and feedback.

##### File structure
- Top-level:
- frontend code in next.config.js, pages/, src/components, hooks/, lib/, styles/
- database/ and supabase/ folders with SQL scripts and migrations
- config files: .env.example, supabase configs, tailwind.config.js, tsconfig.json, vercel.json
- markdown files for deployment, optimization, audits, and feature lists
- pages/api/: Next.js serverless functions act as a lightweight backend and proxy to Supabase or other services.
- src/components/, src/hooks/, src/lib/: modular React UI, hooks, and library code for analytics, caching, cloudinary, mpesa, notifications, etc.
- supabase/migrations/: schema migrations defining tables (users, posts, messages, payments, movies, study groups, etc.)
- public/: static assets, service worker, manifest, UI guidelines

##### README
- Confirms Next.js + React + TypeScript + Tailwind CSS for the frontend
- Supabase for DB, authentication, real-time updates
- Cloudinary for media storage
- Vercel for hosting/deployment, Formspree for form handling

a. Main components
- Client (Next.js React app delivered via Vercel CDN)
- Next.js Serverless API (pages/api/ endpoints)
- Supabase Backend
- Auth service (JWT issuance, RLS enforcement)
- Postgres database (users, posts, comments, messages, relationships, notifications, audit tables)
- Realtime engine (WebSocket channels for feed, chat, notifications)
- Storage (optional, used via Cloudinary for media)
- External services
- Cloudinary (image/video hosting)
- Formspree (feedback forms)
- Mpesa API (mobile payments)
- Possibly email provider via pages/api/send-email
- Third-party monitoring/logging (errorLogger in src/lib)

b. Relationships and interactions
- User’s browser loads the Next.js app (SSR/SSG + client hydration)
- UI makes calls to:
- Next.js API routes for custom logic (e.g. /api/mpesa/pay, /api/send-email)
- Direct Supabase client via src/lib/supabase.ts for auth, queries, subscriptions
- Supabase client SDK connects to Postgres over REST/GraphQL and to Realtime via WebSocket
- Media uploads from UI to Cloudinary; URLs stored in Supabase records
- Notifications emitted via Supabase Realtime and pushed to the client
- Feedback forms posted to Formspree endpoint

c. Architectural patterns and principles
- Full-stack “serverless” model: UI + API co-located in Next.js
- Modular React component library (feature-based folder structure)
- Hook abstraction for data fetching and real-time updates (useSupabase, useWebSocket)
- SQL-first data modeling with migrations; RLS for fine-grained access control
- Single-page-app experience with incremental static regeneration (ISR) where applicable

d. Key technologies/frameworks
- Next.js 14 (pages, API routes, SSR/SSG, middleware)
- React + TypeScript + Tailwind CSS
- Supabase (Auth, Postgres, Realtime)
- Cloudinary for file storage
- Vercel for CI/CD and hosting
- Formspree for form submission

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Tier
    subgraph "Client Tier"
        User["User Browser"]:::external
        Frontend["Next.js Frontend"]:::frontend
        NextConfig["next.config.js"]:::frontend
        ReactUI["React UI"]:::frontend
        Components["React Components"]:::frontend
        Pages["React Pages"]:::frontend
        Hook["useSupabase Hook"]:::frontend
        SupabaseSDK["Supabase SDK"]:::frontend
        SW["Service Worker"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        API["Next.js API Routes"]:::backend
        MpesaPay["mpesa/pay.ts"]:::backend
        MpesaCb["mpesa/callback.ts"]:::backend
        SendEmail["send-email.ts"]:::backend
        LogError["log-error.ts"]:::backend
        AdminDelete["admin-delete-post.ts"]:::backend
    end

    %% Supabase Backend
    subgraph "Supabase Backend"
        Auth["Auth Service"]:::backend
        DB["Postgres Database"]:::backend
        Realtime["Realtime Engine"]:::backend
        Storage["Storage"]:::backend
        Migrations["Supabase Migrations"]:::backend
        SQLScripts["SQL Scripts"]:::backend
    end

    %% External Services
    subgraph "External Services"
        Cloudinary["Cloudinary"]:::external
        Formspree["Formspree"]:::external
        MpesaAPI["Mpesa API"]:::external
        EmailService["Email Provider"]:::external
    end

    %% Connections
    User -->|"loads"| Frontend
    Frontend -->|"REST calls"| API
    Frontend -->|"SDK calls"| SupabaseSDK
    Frontend -->|"WebSocket"| Realtime
    Frontend -->|"upload media"| Cloudinary
    Frontend -->|"submit form"| Formspree

    API -->|"Supabase client"| Auth
    API -->|"Supabase client"| DB
    API -->|"trigger realtime"| Realtime
    API -->|"send payment"| MpesaAPI
    API -->|"send email"| EmailService

    SupabaseSDK -->|"REST queries"| DB
    SupabaseSDK -->|"authenticate"| Auth
    SupabaseSDK -->|"subscribe"| Realtime
    SupabaseSDK -->|"storage ops"| Storage

    Migrations --> DB
    SQLScripts --> DB

    %% Click Events
    click NextConfig "https://github.com/denniswoods383/karu-teens-social-platform/blob/main/next.config.js"
    click Pages "https://github.com/denniswoods383/karu-teens-social-platform/tree/main/src/pages/"
    click Components "https://github.com/denniswoods383/karu-teens-social-platform/tree/main/src/components/"
    click Hook "https://github.com/denniswoods383/karu-teens-social-platform/blob/main/src/hooks/useSupabase.ts"
    click SupabaseSDK "https://github.com/denniswoods383/karu-teens-social-platform/blob/main/src/lib/supabase.ts"
    click SW "https://github.com/denniswoods383/karu-teens-social-platform/blob/main/public/sw.js"
    click MpesaPay "https://github.com/denniswoods383/karu-teens-social-platform/blob/main/src/pages/api/mpesa/pay.ts"
    click MpesaCb "https://github.com/denniswoods383/karu-teens-social-platform/blob/main/src/pages/api/mpesa/callback.ts"
    click SendEmail "https://github.com/denniswoods383/karu-teens-social-platform/blob/main/src/pages/api/send-email.ts"
    click LogError "https://github.com/denniswoods383/karu-teens-social-platform/blob/main/src/pages/api/log-error.ts"
    click AdminDelete "https://github.com/denniswoods383/karu-teens-social-platform/blob/main/src/pages/api/admin-delete-post.ts"
    click Migrations "https://github.com/denniswoods383/karu-teens-social-platform/tree/main/supabase/migrations/"
    click SQLScripts "https://github.com/denniswoods383/karu-teens-social-platform/tree/main/database/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef backend fill:#DFFFE0,stroke:#28a745,stroke-width:1px
    classDef external fill:#FFF5B1,stroke:#dbab09,stroke-width:1px
```
