Skip to main content

Developer Guide Overview

This guide covers the technical architecture of Artbase Studio for developers who want to contribute, extend, or integrate with the platform.

Architecture Summary​

Artbase Studio is built as a modern, multi-tenant SaaS platform with the following stack:

LayerTechnology
Frontend (Mobile)Flutter with Riverpod state management
Frontend (Web)Next.js 15 App Router
BackendNext.js API Routes + Supabase Edge Functions
DatabasePostgreSQL via Supabase
AuthenticationSupabase Auth (email, OAuth)
PaymentsStripe (Checkout, Payment Intents)
EmailResend API
File StorageSupabase Storage
Background JobsRailway services
SearchAlgolia (product search)

Repository Structure​

artbase/
├── apps/
│   ├── creator_hub/          # Flutter mobile app
│   │   ├── lib/
│   │   │   ├── core/         # Providers, models, services
│   │   │   ├── features/     # Feature modules
│   │   │   └── main.dart
│   │   └── pubspec.yaml
│   ├── web/                  # Next.js web app
│   │   ├── src/
│   │   │   ├── app/          # App Router pages & API routes
│   │   │   ├── components/   # React components
│   │   │   └── lib/          # Utilities and helpers
│   │   └── package.json
│   └── docs/                 # This documentation site
├── services/                 # Railway background services
│   ├── etsy-sync/
│   ├── gumroad-sync/
│   ├── analytics-aggregator/
│   ├── scheduled-send/
│   ├── automation-processor/
│   ├── guest-cleanup/
│   ├── cart-abandonment/
│   └── shared/               # Shared utilities
├── supabase/
│   ├── migrations/           # Database migrations
│   └── functions/            # Edge functions
└── packages/                 # Shared packages

Key Concepts​

Multi-Tenancy​

Every organization (creator store) is isolated through PostgreSQL Row-Level Security (RLS). All tables include an org_id foreign key, and RLS policies ensure users can only access data belonging to their organization.

-- Example RLS policy
CREATE POLICY "Users can view own org products"
  ON products FOR SELECT
  USING (org_id IN (
    SELECT org_id FROM organization_members
    WHERE user_id = auth.uid()
  ));

Authentication Flow​

  1. User signs up/in via Supabase Auth
  2. JWT token issued with user claims
  3. API routes verify token via createClient()
  4. RLS policies enforce data access based on user's organizations

Commission Model​

Platform fees are calculated during checkout:

// Founding artists (first 2 years): 0% commission
// Standard plans: commission_rate from plan features
const isFoundingArtistActive = org.is_founding_artist &&
  org.founding_artist_start_date &&
  (Date.now() - new Date(org.founding_artist_start_date).getTime()) < TWO_YEARS_MS;

const platformFee = isFoundingArtistActive ? 0 : amount * commissionRate;

Development Setup​

Prerequisites​

  • Node.js 18+
  • pnpm 8+
  • Flutter 3.16+
  • Supabase CLI
  • Docker (for local Supabase)

Quick Start​

# Clone repository
git clone https://github.com/artbase/artbase-studio.git
cd artbase-studio

# Install dependencies
pnpm install

# Start local Supabase
supabase start

# Run database migrations
supabase db push

# Start web app
cd apps/web && pnpm dev

# Start Flutter app (separate terminal)
cd apps/creator_hub && flutter run

Environment Variables​

Create .env.local in apps/web/:

NEXT_PUBLIC_SUPABASE_URL=http://localhost:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
RESEND_API_KEY=re_...

Next Steps​