Technical Stack - joinruach/JoinRuach GitHub Wiki

Technical Stack

Architecture Overview

Ruach Studios is built on a modern, scalable, faith-driven tech stack designed for performance, maintainability, and developer experience.

We prioritize:

  • Type safety — Catch errors before production
  • Modularity — Components that can be reused and extended
  • Performance — Fast load times and smooth interactions
  • Developer experience — Tools that don't fight you

Core Technologies

Frontend

Framework

  • Next.js 14+ (App Router)
    • Server-side rendering (SSR) and static generation (SSG)
    • API routes for backend logic
    • Built-in optimization for images, fonts, and scripts

Language

  • TypeScript 5+
    • Full type coverage
    • Strict mode enabled
    • Zod for runtime validation

UI Library

  • React 18+
    • Server Components where applicable
    • Client Components for interactivity
    • Hooks for state management

Styling

  • Tailwind CSS 3+
    • Custom design tokens
    • Component-based utility classes
    • Dark mode support
  • CSS Modules (where Tailwind isn't ideal)
  • Framer Motion for animations

State Management

  • React Context for global state
  • Zustand for complex client-side state
  • React Query (TanStack Query) for server state

Forms

  • React Hook Form — Form handling
  • Zod — Schema validation

Backend

Runtime

  • Node.js 20+ (LTS)
  • Bun (experimental) for faster builds

Framework

  • Next.js API Routes (for simple APIs)
  • tRPC (for type-safe APIs)
  • Express.js (for standalone services)

Database

  • PostgreSQL 16+ (Primary database)
    • Relational data storage
    • ACID compliance
    • PostGIS for geospatial data
  • Redis (Caching and sessions)
  • Prisma ORM (Database access layer)

Authentication

  • NextAuth.js (Auth.js v5)
    • OAuth providers (Google, GitHub)
    • Email magic links
    • JWT and session management

File Storage

  • AWS S3 or Vercel Blob for media files
  • Cloudflare R2 (alternative for cost efficiency)

Infrastructure

Hosting

  • Vercel (Frontend and API routes)
  • Railway or Fly.io (Standalone services)
  • AWS (Enterprise-scale infrastructure)

CI/CD

  • GitHub Actions
    • Automated testing
    • Linting and formatting
    • Deployment pipelines

Monitoring

  • Sentry (Error tracking)
  • Vercel Analytics (Performance monitoring)
  • PostHog (Product analytics)

Email

  • Resend (Transactional emails)
  • React Email (Email templates)

Media & Content

CMS

  • Sanity.io or Contentful
    • Structured content for blog posts, articles, and media
    • Real-time collaboration
    • Preview and draft modes

Video

  • Mux (Video hosting and streaming)
  • Cloudflare Stream (Alternative)

Image Optimization

  • Next.js Image Component (Automatic optimization)
  • Cloudinary (Advanced transformations)

AI & Automation

AI Integration

  • OpenAI GPT-4 (Content generation, summarization)
  • Anthropic Claude (Contextual assistance)
  • Replicate (AI models for media processing)

Automation

  • n8n or Zapier (Workflow automation)
  • GitHub Actions (CI/CD automation)

Development Tools

Code Quality

Linting & Formatting

  • ESLint (Code linting)
  • Prettier (Code formatting)
  • Husky (Git hooks for pre-commit checks)

Testing

  • Vitest (Unit and integration tests)
  • Playwright (End-to-end tests)
  • React Testing Library (Component tests)

Type Checking

  • TypeScript (Static type checking)
  • tsc (TypeScript compiler)

Version Control

  • Git (Version control)
  • GitHub (Repository hosting)
    • Branch protection rules
    • Pull request reviews
    • Issue tracking

Package Management

  • pnpm (Preferred for speed and efficiency)
  • npm (Fallback)

Security

Best Practices

  • Environment Variables — Stored in .env.local, never committed
  • API Keys — Managed via Vercel environment variables
  • Authentication — JWT tokens with short expiration
  • Data Validation — Zod schemas on all inputs
  • SQL Injection Prevention — Prisma parameterized queries
  • XSS Protection — React's built-in escaping + CSP headers
  • CORS — Restricted origins for API routes

Compliance

  • GDPR — User data privacy and consent
  • CCPA — California privacy compliance
  • COPPA — Child safety protections

API Architecture

tRPC Endpoints

Example Structure:

import { z } from 'zod';
import { router, publicProcedure } from './trpc';

export const appRouter = router({
  getContent: publicProcedure
    .input(z.object({ id: z.string() }))
    .query(async ({ input }) => {
      // Fetch content by ID
    }),
  
  createContent: publicProcedure
    .input(z.object({ title: z.string(), body: z.string() }))
    .mutation(async ({ input }) => {
      // Create new content
    }),
});

REST API (Express)

For standalone services not tied to Next.js:

import express from 'express';

const app = express();

app.get('/api/health', (req, res) => {
  res.json({ status: 'ok' });
});

app.listen(3001);

Database Schema

Prisma Schema Example

model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String?
  createdAt DateTime @default(now())
  posts     Post[]
}

model Post {
  id        String   @id @default(cuid())
  title     String
  content   String
  published Boolean  @default(false)
  authorId  String
  author    User     @relation(fields: [authorId], references: [id])
  createdAt DateTime @default(now())
}

Performance Targets

  • First Contentful Paint (FCP): < 1.5s
  • Largest Contentful Paint (LCP): < 2.5s
  • Time to Interactive (TTI): < 3.5s
  • Cumulative Layout Shift (CLS): < 0.1
  • Lighthouse Score: > 90

Environment Setup

See Development Setup for full instructions.

Required Tools:

  • Node.js 20+
  • pnpm 8+
  • PostgreSQL 16+
  • Git

Optional Tools:

  • Docker (for containerized databases)
  • Postman or Insomnia (API testing)

Deployment

Vercel (Frontend)

vercel --prod

Railway (Backend Services)

railway up

Database Migrations

pnpm prisma migrate deploy

Architecture Decisions

Why Next.js?

  • Best-in-class React framework
  • Built-in performance optimizations
  • Server-side rendering and API routes in one package
  • Large ecosystem and community support

Why Prisma?

  • Type-safe database queries
  • Intuitive schema modeling
  • Excellent migration system
  • Auto-generated TypeScript types

Why tRPC?

  • End-to-end type safety without code generation
  • No REST boilerplate
  • Perfect for monorepo architectures
  • Seamless integration with Next.js

Why Tailwind CSS?

  • Utility-first approach increases development speed
  • No naming conventions to debate
  • Built-in design system via config
  • Excellent performance (no unused CSS)

Future Considerations

Planned Additions

  • GraphQL (for complex data fetching)
  • Microservices (for scaling specific features)
  • Mobile Apps (React Native or Flutter)
  • Blockchain (for NFTs or decentralized media)

Experimental Tech

  • Bun (faster JavaScript runtime)
  • Astro (for marketing pages)
  • Rust (for performance-critical services)

Questions?

If you have questions about the technical stack:

"Whatever your hand finds to do, do it with all your might." — Ecclesiastes 9:10