Project Structure

CommonPlace follows a standard React + Vite project structure with some conventions specific to our architecture.

Root Directory

friends-network/
├── src/                    # React application source
├── supabase/              # Database migrations (PostgreSQL + RLS)
├── docs/                  # This documentation (Docusaurus)
├── extension/             # Browser extension (Chrome/Edge)
├── public/                # Static assets
├── scripts/               # Dev & CI scripts
├── .claude/               # Claude Code configuration
├── package.json           # Dependencies and scripts
├── vite.config.js         # Vite configuration
├── eslint.config.js       # ESLint configuration
├── .env.example           # Environment variable template
├── .gitignore             # Git ignore rules
└── README.md              # Project readme

Source Directory (src/)

src/
├── App.jsx               # Routing (14 active routes)
├── main.jsx              # Vite entry point
├── index.css             # Global styles (~9,600 lines)
├── components/           # React components (26 subdirectories)
│   ├── account/          # Account-level components
│   ├── admin/            # Admin panel modals and widgets
│   ├── circles/          # Circle management (create, charter, invite)
│   ├── clips/            # External content clips
│   ├── common/           # Shared UI utilities (MessageButton, etc.)
│   ├── composer/         # Post composition tools
│   │   └── editors/      # Editor types (drawing, longform, poetry, simple)
│   ├── dev/              # Development tools (theme switcher, feedback)
│   ├── friends/          # Friend management (FriendButton, block, search)
│   ├── HowItWorks/       # Onboarding slideshow
│   ├── invites/          # Invite link management
│   ├── mebook/           # MeBook system
│   │   ├── inputs/       # MeBook input types (7 types)
│   │   └── screens/      # MeBook flow screens (7 screens)
│   ├── messaging/        # Chat and messaging (14 components)
│   ├── modules/          # HomeRoom modules (10 module types)
│   ├── notifications/    # Notification system
│   ├── post/             # Post display helpers
│   ├── post-parts/       # Post sub-components (header, content, actions, etc.)
│   ├── posts/            # Post feature components
│   ├── profile/          # Profile display
│   ├── relationships/    # Relationship management
│   ├── report/           # Report system
│   ├── room/             # HomeRoom customization
│   │   ├── layouts/      # Room layout engines (6 layouts)
│   │   └── style-controls/ # Room style editors (5 controls)
│   ├── settings/         # Settings panels (5 panels)
│   ├── sharing/          # Post sharing (ShareButton, SharedPostCard)
│   ├── ui/               # Reusable UI primitives (Modal, Toast, BottomSheet)
│   └── voice/            # Voice narration (recorder, player, context)
├── hooks/                # Custom React hooks (43 hooks)
├── context/              # React context providers
│   ├── ThemeContext.jsx
│   ├── MessagingContext.jsx
│   └── AnnouncerContext.jsx
├── pages/                # Page-level components
│   ├── Messages.jsx
│   ├── FindPage.jsx
│   ├── JoinPage.jsx
│   ├── MeBookPage.jsx
│   ├── UserStorage.jsx
│   ├── ClipsQueue.jsx
│   ├── AdminTest.jsx
│   └── admin/            # Admin panel pages (9 files)
└── lib/                  # Utilities and configuration
    ├── supabase.js       # Supabase client init
    ├── encryption.js     # Encryption utilities
    ├── sanitize.js       # HTML sanitization
    ├── googleFonts.js    # Google Fonts integration
    ├── fontVoices.js     # Font voice mappings
    ├── layoutModes.js    # Room layout definitions
    ├── roomStyleUtils.js # Room style utilities
    ├── welPrompts.js     # Welcome prompt content
    ├── constants/        # Constant definitions (intents, fonts)
    ├── shortcodes/       # Shortcode parser and renderers
    └── utils/            # Utility functions (date, string, clipboard)

Key Conventions

Components

• One component per file
• Named exports preferred
• CSS modules (.module.css) or co-located CSS files
• Each subdirectory has an index.js barrel export

Hooks

• Prefix with use
• Handle loading and error states
• Return consistent object shapes
• Encapsulate Supabase queries

Context

• Used for global state only
• Avoid prop drilling
• Theme, Auth, Messaging are global

Database Migrations

supabase/migrations/          # 40+ migration files
├── 20260130_homeroom_foundation.sql
├── 20260130_avatar_library.sql
├── 20260130_mebook_system.sql
├── 20260131_circles_schema.sql
├── 20260131_messaging_system.sql
├── 20260202_admin_system.sql
├── 20260205_rate_limiting_fixed.sql
├── 20260205_account_tiers.sql
├── 20260205_block_enhancement.sql
├── 20260205_browser_extension.sql
├── 20260207_admin_report_functions.sql
└── ...

Migrations are numbered by date (YYYYMMDD) and describe the feature.

Adding New Code

Type	Location
New feature component	src/components/[feature]/
New hook	src/hooks/use[Name].js
New page	src/pages/[Name].jsx or src/components/[Name].jsx
New context	src/context/[Name]Context.jsx
New utility	src/lib/utils/[name].js or src/lib/[name].js
Database change	supabase/migrations/YYYYMMDD_[description].sql

---

Last updated: 2026-02-07