Architecture Overview

CommonPlace follows a modern JAMstack architecture with React on the frontend and Supabase providing backend services.

System Diagram

┌─────────────────────────────────────────────────────────────────┐
│                        Client (Browser)                         │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                    React Application                     │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐ │   │
│  │  │Components│  │  Hooks   │  │ Context  │  │  Pages  │ │   │
│  │  └──────────┘  └──────────┘  └──────────┘  └─────────┘ │   │
│  └─────────────────────────────────────────────────────────┘   │
│                              │                                  │
│                              ▼                                  │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                   Supabase Client                        │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                               │
                               │ HTTPS
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Supabase Cloud                           │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────────────┐ │
│  │   Auth   │  │   API    │  │ Storage  │  │   PostgreSQL    │ │
│  │(GoTrue)  │  │(PostgREST)│  │          │  │    Database     │ │
│  └──────────┘  └──────────┘  └──────────┘  │  ┌───────────┐  │ │
│                                            │  │    RLS    │  │ │
│                                            │  │  Policies │  │ │
│                                            │  └───────────┘  │ │
│                                            └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

Key Components

Frontend (React + Vite)

Component	Purpose
Components	Reusable UI elements
Hooks	Data fetching and state logic
Context	Global state (theme, auth, messaging)
Pages	Route-level components

Backend (Supabase)

Service	Purpose
Auth	User authentication via GoTrue
Database	PostgreSQL with Row Level Security
Storage	File uploads (images, media)
Realtime	Live subscriptions for messaging

Data Flow

1. User Action → Component captures interaction
2. Hook Call → Custom hook makes Supabase request
3. RLS Check → Database validates permissions
4. Response → Data returned to component
5. Render → UI updates with new data

Authentication Flow

User Login
    │
    ▼
┌──────────────┐
│ Auth.signIn  │
└──────────────┘
    │
    ▼
┌──────────────┐     ┌──────────────┐
│   Supabase   │────▶│   Session    │
│    Auth      │     │   Created    │
└──────────────┘     └──────────────┘
    │
    ▼
┌──────────────┐
│  App State   │
│   Updated    │
└──────────────┘
    │
    ▼
┌──────────────┐
│  Protected   │
│   Routes     │
│  Accessible  │
└──────────────┘

Security Model

All data access is controlled by Row Level Security (RLS) policies in PostgreSQL:

• Users can only see their own data (posts, settings)
• Friends can see shared content (feed posts)
• Blocked users are completely invisible (404, not "blocked")
• Admin functions require is_admin flag

See Database Security for policy details.

File Structure

friends-network/
├── src/
│   ├── components/     # React components
│   ├── hooks/          # Custom React hooks
│   ├── context/        # React context providers
│   ├── pages/          # Page-level components
│   ├── lib/            # Utilities and configuration
│   └── index.css       # Global styles
├── supabase/
│   └── migrations/     # Database migrations
├── docs/               # This documentation
└── public/             # Static assets

See File Structure for detailed breakdown.