NOOR SOCIAL OS
The social media operating system for agencies, businesses, and creators. Powered by Noor Studio Agency.
One workspace per brand or client to plan, schedule, and measure content across
Instagram, TikTok, Facebook, YouTube, LinkedIn, X, and Pinterest. Every number
says where it came from, and nothing is shown as connected or published without
the platform confirming it.
Status: the product, data model, security model, publishing pipeline,
billing, and admin tooling are built and tested. Real platform connections
and publishing are not: the seven platform adapters are placeholders
awaiting developer apps and app reviews. See docs/STATUS.md
for the full picture.
Contents
What's inside
| Area | Highlights |
|---|
| Workspaces | Organizations with brand and client workspaces, roles (Owner, Admin, Editor, Analyst, Viewer), invitations, client guests who only see their own workspace |
| Social accounts | Manual tracking for imports, demo accounts, OAuth + PKCE machinery with encrypted token storage (adapters pending) |
| Content Studio | Drafts, captions, hashtags, media, per-platform overrides, live validation against each platform's rules |
| Calendar | Month and week views, planned dates, scheduling in the workspace's time zone |
| Publishing | Durable queue with idempotency keys, retries with backoff, blocked/failed/unknown outcomes, worker or cron |
| Analytics | Dashboard and explorer with provenance and freshness, CSV import, per-platform metric availability |
| AI Assistant | Ideas, captions, hooks, hashtags, campaigns, and adaptations via Claude, or labelled demo templates |
| Billing | Free, Starter, Pro, Agency; usage meters; Stripe Checkout, portal, and verified webhooks |
| Admin | Platform overview, health, organizations, users, failed jobs, audit log |
Stack: Next.js 16 (App Router, Cache Components, Partial Prerendering),
TypeScript, Tailwind CSS 4, Supabase (Auth, Postgres, Storage), Kysely + pg,
Zod, Recharts, Radix UI, Framer Motion, Stripe SDK, Anthropic SDK, Vitest,
Playwright.
Architecture
The short version:
- All data access runs on the server against Postgres. User requests run
inside a transaction as the
authenticated role with server-verified JWT
claims, so Row Level Security applies to every query, exactly as it would
through Supabase's API (ADR-001).
- Supabase is used for Auth and Storage; the browser never holds a Supabase
session it can read (HttpOnly cookies).
- Privileged work (publishing jobs, tokens, billing, audit) uses a separate
system connection, reached only after a server-side authorization check.
- Security-definer SQL functions perform multi-table transitions (create an
organization, schedule a post, accept an invitation) and check the caller's
role themselves.
Read more: docs/ARCHITECTURE.md,
docs/SECURITY.md, docs/DESIGN-SYSTEM.md.
src/app/ routes: marketing, auth, onboarding, /w/[workspace]/…, /admin, /api
src/components/ design system and app shell
src/features/ client components per product area
src/lib/ client-safe shared code (permissions, platforms, validation, time)
src/server/ server-only code: auth, db, services, integrations, publishing,
analytics, ai, billing, security, observability
supabase/ SQL migrations (schema, RLS, functions)
tests/ unit, database (RLS), and integration suites
e2e/ Playwright end-to-end tests
scripts/ worker, dev seed, admin grant
tooling/ local Postgres shim and test-only auth emulator
Local development
Requirements: Node.js 22+, pnpm 10+, and PostgreSQL 16+ (or Docker for the
Supabase CLI).
Option A: no Docker (fastest)
Uses your local Postgres plus a small Supabase-compatible schema shim and a
test-only auth emulator. The emulator refuses to run with
NODE_ENV=production and must never be deployed.
pnpm install
cp .env.example .env.local
Fill .env.local with local values:
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=local-publishable-key # any value; the emulator ignores it
SUPABASE_SERVICE_ROLE_KEY=local-service-role-key # the emulator's default admin key
DATABASE_URL=postgresql://postgres:[email protected]:5432/noor_dev
TOKEN_ENCRYPTION_KEYS=v1:<output of: openssl rand -base64 32>
TOKEN_ENCRYPTION_ACTIVE_KEY_ID=v1
IP_HASH_SECRET=<openssl rand -hex 32>
CRON_SECRET=<openssl rand -hex 32>
Then:
pnpm db:reset # creates noor_dev: shim + every migration
pnpm db:seed # demo agency, users, clients, and a demo workspace
# terminal 1
DATABASE_URL=postgresql://postgres:[email protected]:5432/noor_dev \
APP_URL=http://localhost:3000 pnpm auth:emulator
# terminal 2
pnpm dev
Open http://localhost:3000 and sign in as [email protected] (owner and platform
admin), [email protected] (editor), or [email protected] (client guest).
The seed prints the shared local password. Emails the emulator "sends" are
written to .local/auth-emulator-mail.log.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
