System Architecture

Technical architecture documentation for the TendSocial platform.

Overview

TendSocial is a multi-tenant SaaS platform built with:

• Backend: Node.js + Fastify + Prisma 7
• Frontend: React 19 + Vite + TailwindCSS
• Database: PostgreSQL (NeonDB)
• Auth: Supabase Auth
• AI: Multi-provider via Vercel AI Gateway

Documentation

Core Architecture

• Architecture Overview - Complete system design including:

  • Request lifecycle
  • Authentication flow
  • Data models
  • Security architecture
  • Scalability patterns

• Tech Stack - Technologies and versions:

  • Node 24, TypeScript 5.6+
  • Prisma 7, React 19
  • Fastify 5, Zod 3

• Database Schema - Data model documentation:

  • Core multi-tenant models
  • Prisma schema overview
  • Model relationships

Scaling & Multi-Tenancy

• Multi-Tenancy - Agency and team architecture:
  • Many-to-many user-company relationships
  • Context switching for agencies
  • Data isolation patterns
• Tenant Isolation - Two-layer defense against cross-tenant leaks:
  • App-layer guard, escape hatch, and the Accelerate extension-ordering rule
  • Postgres Row-Level Security as a database-level backstop
  • The cross-tenant RLS bypass sentinel

Async Processing

• Cloud Tasks - Background job processing:
  • Google Cloud Tasks integration
  • Task queues and retries
  • Scheduled jobs

Prisma Postgres Evaluation

• Prisma Postgres Evaluation - Spike plan: phase breakdown, decision targets, and success criteria
• Prisma Postgres Setup - Environments, split pooled/direct connections, schema creation, and seeding
• Operation Testing - Measurement suites: API, standard Playwright, and exhaustive crawl
• DB Tuning - N+1 elimination, over-fetching, pagination, bulk writes, background jobs
• Indexing - Workload-driven indexes with before/after validation
• Caching - Three-layer cache (Accelerate, request-scope, in-process) with invalidation
• Analytics Offload - Classify and route high-volume writes out of Prisma
• Decision Gate - Go/no-go criteria, cost forecast, rollout, and rollback plan

AI System

• AI Models Configuration - AI model task mapping:
  • Task ID → Feature mapping
  • Model tiers (Opus/Sonnet/Haiku)
  • Cost breakdown

Key Patterns

Pattern	Description
Tenant Isolation	All queries scoped via getTenantPrisma(companyId)
JWT Auth	Supabase tokens verified, user info from NeonDB
ESM Modules	All imports use .js extensions
Type Safety	Zod for validation, TypeScript strict mode

See Also

• Tech Stack - Full technology list
• Database Schema - Prisma models
• Contributing - Development setup