FolkTheory Documentation

Technical documentation for the FolkTheory platform

View on GitHub

FolkTheory - Startup Ecosystem Platform

From Idea to Impact – a unified platform where founders find co‑founders, validate ideas, build startups, and connect with investors. FolkTheory blends community, collaboration, and capital into one focused workflow (no context‑switching between 5 fragmented tools).

Tagline: “From Idea to Impact – Build, Collaborate, Fund”

📚 Table of Contents

  1. Platform Overview
  2. Technical Architecture
  3. Platform Features
  4. Security Implementation
  5. Work in Progress
  6. Services & Integrations
  7. Development Setup
  8. Environment Variables
  9. Performance Optimization
  10. Platform Metrics
  11. Architecture Diagram
  12. Messaging Data Flow
  13. Contributing
  14. License

Deployed on Vercel Built with Next.js Fastly Edge MongoDB Redis TypeScript

🎯 Platform Overview

FolkTheory is a comprehensive startup ecosystem platform that enables aspiring entrepreneurs to connect, collaborate, and secure funding. The platform combines the best aspects of:

🏗️ Technical Architecture

Core Technology Stack

Component Technology Version Purpose
Frontend Next.js 15.5.9 React-based web framework with SSR & Turbopack
UI Framework React 19.2.0 Component-based user interface
Language TypeScript 5+ Type-safe development with typed routes
Styling Tailwind CSS 3.4.17 Utility-first CSS framework
UI Components Radix UI Latest Accessible component library
Authentication NextAuth.js 4.24.11 Secure authentication system
Database MongoDB 7.0.20 Document-based database with real-time monitoring
ODM Mongoose 8.16.4 MongoDB object modeling
Cache Redis 7.2.5 High-performance caching with auto-pipelining
Redis Client IORedis 5.8.2 Node.js Redis client with enhanced TLS support
Real-time Messaging Ably Latest WebSocket-based real-time pub/sub (6M msg/month free)
Validation Zod 3.24.1 TypeScript-first schema validation
Testing Vitest 2.1.9 Fast unit test framework
Logging Custom Logger - Structured logging with multiple levels
Hosting Vercel - Deployment and hosting platform
File Storage Cloudflare R2 + Fastly OS - Multi-cloud file storage with automatic failover
Edge Computing Fastly Compute@Edge v60 (Rust) ✅ PRODUCTION - Edge gateway with JWT auth, rate limiting, bot blocking
Analytics Vercel Analytics 1.5.0 Performance monitoring
Theme System next-themes Latest Light/Dark/System theme switching
WebRTC Cloudflare Calls Latest Real-time voice and video calling
Video Infrastructure Cloudflare SFU - Global Selective Forwarding Unit for scalable media

Development Tools

Recent Updates (December 2025)

Real-Time Messaging Upgrade:

Security & Infrastructure:

UX Improvements:

Previous Updates (November 2025):

Code Quality & Refactoring:

Previous Updates (October 2025):

Framework Upgrades:

Code Quality Improvements:

🚀 Platform Features

✅ Implemented Core Features

1. User Authentication & Management

Signup Password Requirements:
✅ Minimum 6 characters
✅ At least 1 capital letter (A-Z)
✅ At least 1 special character (@#$%^&*!)
✅ At least 1 number (0-9)

2. Co-founder & Team Matching

3. Startup & Project Management

4. Investor Portal

5. Community Features

6. Dashboard & Analytics

7. Search & Discovery

8. Messaging System ⚡ ABLY REAL-TIME POWERED

9. Admin Dashboard 🎛️ ENHANCED WITH REDIS 7.2.5

10. File Management ☁️ MULTI-CLOUD WITH FAILOVER

11. Modern UI/UX with Theme System 🎨

12. Real-Time Voice & Video Calling 📞 CLOUDFLARE CALLS POWERED

🔒 Security Implementation

Current Strengths

⚠️ Security Vulnerabilities

Priority Vulnerability Location Risk Level Impact
🔴 Critical Hardcoded DB Credentials lib/mongodb.ts High Full database access
🔴 Critical Hardcoded Redis Credentials lib/redis-client.ts High Cache/session access
🔴 Critical Weak/Hardcoded NEXTAUTH_SECRET lib/auth.ts High Session compromise
✅ FIXED No Rate Limiting lib/rate-limit.ts Low Multiple presets implemented
✅ FIXED Limited Input Sanitization lib/validation.ts Low Zod + sanitization utils
🟡 Medium Missing CSRF Protection Forms Medium Consider CSRF tokens
✅ FIXED Exposed Error Details lib/logger.ts Low Structured logging

🚧 Work in Progress (WIP) Elements

✅ Phase 2 Completed (Recent Updates - December 2025)

🔧 Phase 3 In Progress (Current Focus - December 2025)

Edge Computing Layer:

Authentication Improvements:

Phase 4 Planned Features (Q1-Q2 2026)

Missing Core Components

Known Issues & Blockers

Issue Status Priority Impact Reference
Fastly Routing Mystery ✅ RESOLVED Closed Was stale WASM + cache /docs/fastly/FASTLY_DEBUG_RESULTS.md
Hardcoded DB Credentials 🔴 SECURITY Critical Production security risk lib/mongodb.ts, lib/redis-client.ts
Missing Email Service 🟡 FEATURE GAP High Cannot send user notifications N/A
No CSRF Protection 🟡 SECURITY Medium Form vulnerability Forms across app

📊 Database & Caching Architecture

MongoDB Primary Database

The main data storage using MongoDB for document-based persistence with optimized indexing:

Redis Caching Layer ⚡ ENTERPRISE-GRADE

High-performance caching and real-time features using Redis ObjectRocket HA:

Performance Achievements:

Operation Before (Database) After (Redis Cache) Improvement
Message Retrieval ~300ms ~12ms 25x faster
Conversation Loading ~200ms ~8ms 25x faster
Rate Limiting ~50ms ~2ms 25x faster
Real-time Updates Polling (1000ms) Pub/Sub (~30ms) 33x faster
Search Results No caching Instant repeats Infinite improvement

Redis Features Implemented:

User Model Features

interface IUser {
  email: string              // Unique, validated email
  password: string          // bcrypt hashed (min 6 chars, 1 capital, 1 special @#$%^&*!, 1 number)
  firstName: string         // User's first name
  lastName: string          // User's last name
  userType: enum            // founder, investor, cofounder, mentor, advisor
  bio?: string              // Profile description
  location?: string         // Geographic location
  linkedinUrl?: string      // LinkedIn profile
  skills: string[]          // Technical and business skills
  experience: enum          // 0-1, 1-3, 3-5, 5-7, 7-10, 10+ years
  availability: enum        // full-time, part-time, consulting, not-available
  industries: string[]      // Focus industries
  startupId?: ObjectId      // Reference to associated startup
  isOnline?: boolean        // Online status
  lastSeen?: Date          // Last activity timestamp
}

Database & Cache Optimizations

MongoDB Optimizations:

Redis Performance Enhancements:

🌟 Platform Strengths

Technical Excellence

User Experience

Business Logic

Development Experience

📋 Recommendations

✅ Recently Completed Improvements

  1. Message Cache Fix: ✅ COMPLETED - Fixed cache invalidation with specific key targeting
  2. Performance Optimization: ✅ COMPLETED - 25x faster messaging with Redis
  3. Log Cleanup: ✅ COMPLETED - Eliminated development log spam
  4. Theme System: ✅ COMPLETED - Modern Light/Dark theme toggle
  5. Mobile Navigation: ✅ COMPLETED - Responsive hamburger menu
  6. Header Optimization: ✅ COMPLETED - Black-translucent navigation bar

🔴 Immediate Security Fixes

  1. Environment Variables: Move all MongoDB/Redis credentials to secure vaults
  2. Input Sanitization: Add comprehensive XSS protection
  3. Secret Rotation: Generate strong NEXTAUTH_SECRET
  4. Error Handling: Remove sensitive information from remaining logs
  5. CSRF Protection: Implement cross-site request forgery protection

🟡 Short-term Improvements

  1. Testing Suite: Implement Jest/Cypress testing
  2. Error Monitoring: Add Sentry or similar service
  3. CI/CD Pipeline: Automated testing and deployment
  4. API Documentation: OpenAPI/Swagger documentation
  5. Performance Monitoring: Extend Redis cache analytics

🟢 Long-term Enhancements

  1. Microservices: Break into smaller, focused services
  2. CDN Implementation: Global content delivery
  3. WebSocket Integration: True real-time connections beyond pub/sub
  4. Analytics Platform: Custom analytics dashboard
  5. Machine Learning: AI-powered matching algorithms
  6. Mobile App: Native iOS/Android applications

🌐 Edge Computing Layer (Fastly Compute@Edge)

Architecture Overview

FolkTheory uses Fastly Compute@Edge as an edge computing gateway deployed at 300+ global points of presence. The service is written in Rust and compiled to WebAssembly (WASM) for high-performance edge execution.

Service Details:

Planned Edge Features

The Fastly Compute gateway is designed to provide:

  1. JWT Authentication at Edge (src/auth.rs)
    • Validate tokens before origin hit
    • 0.5ms vs 20ms origin validation
    • Reduces database load by 75%
  2. Distributed Rate Limiting (src/rate_limit.rs)
    • Per-user sliding window rate limits
    • KV Store-backed counters
    • Prevents abuse before reaching origin
  3. Smart Caching (src/cache.rs)
    • Configurable TTLs per route
    • Request coalescing for hot paths
    • 10-100x reduction in origin requests
  4. Presigned URL Generation (src/presigned.rs)
    • Generate S3 presigned URLs at edge
    • 100% origin offload for uploads
    • Direct client → R2 uploads
  5. Media Serving (src/media.rs)
    • Serve assets from Fastly Object Storage
    • Automatic failover to Cloudflare R2
    • Global CDN with 1-year cache
  6. WebSocket Routing (src/main.rs)
    • Route WebSocket connections to origin
    • Preserve WebSocket upgrade headers
    • Low-latency global routing

Current Status: Debugging Routing Issue ⚠️

Problem: Some routes execute WASM correctly while others bypass and proxy directly to origin.

Route Status Behavior
GET /health ✅ Working Returns “OK” from WASM
GET / ✅ Working Returns HTML from WASM
GET /test123 ❌ Bypassed Proxies to origin → Vercel 404
GET /api/* ❌ Bypassed Proxies to origin

Evidence: Response headers show server: Vercel for bypassed routes, proving request goes to origin instead of being handled by edge code.

Hypothesis: Service-level routing rule or path condition in Fastly dashboard is intercepting certain paths before WASM execution.

Support Ticket: Open with Fastly Support (Yasunori)
Reference: /FASTLY_ROUTING_MYSTERY.md
Support Package: /fastly-support-package.zip (includes WASM binary and source)

Fastly Compute Dependencies (Rust)

[dependencies]
fastly = "0.10"           # Fastly Compute SDK
serde = "1.0"            # Serialization
serde_json = "1.0"       # JSON handling
base64 = "0.22"          # Base64 encoding
hex = "0.4"              # Hex encoding
sha2 = "0.10"            # SHA256 hashing
hmac = "0.12"            # HMAC signatures
chrono = "0.4"           # Date/time handling

Files & Documentation

Source Code:

Configuration:

Documentation:

Scripts:

Expected Performance (Once Routing Fixed)

Metric Before (Origin Only) After (Edge) Improvement
JWT Validation 20ms 0.5ms 40x faster
Conversations P95 200ms 8ms 25x faster
Messages P95 150ms 10ms 15x faster
Profile P95 100ms 5ms 20x faster
Upload P95 250ms 2ms 125x faster
Origin Requests 100% 25% 75% reduction

🛠️ Services & Integrations

Current Integrations

Service Purpose Status Configuration
ObjectRocket MongoDB Primary database ✅ Active 50GB, iad2-c19 cluster
ObjectRocket Redis HA Caching & pub/sub ✅ Active 20GB, SSL/TLS, Redis 7.2.5
Ably Realtime WebSocket messaging ✅ Active 6M msg/month, 200 connections
Cloudflare R2 Primary file storage ✅ Active S3-compatible, SDK v3.848.0
Fastly Object Storage Backup file storage ✅ Active us-east region, automatic failover
Fastly Compute@Edge Edge gateway (WASM) ✅ Production Service: BYJaPC4AwQ5AtvJtTbcQTO, v60
Cloudflare Calls WebRTC voice/video ✅ Active Global SFU, 330+ edges
Vercel Hosting Application deployment ✅ Active Auto-deploy from Git
NextAuth.js Authentication ✅ Active JWT strategy
Vercel Analytics Performance tracking ✅ Active Real-time metrics
next-themes Theme system ✅ Active Light/Dark/System modes

Planned Integrations

Service Purpose Priority Timeline
Stripe Payment processing High Phase 3
SendGrid/Mailchimp Email services High Phase 3
Zoom API Video meetings (backup) Low Phase 4
LinkedIn OAuth Social login Medium Phase 3
Sentry Error monitoring Medium Phase 3
WebSocket Server Extended real-time features Low Phase 4

Note: Cloudflare Calls already provides enterprise-grade video calling, so Zoom integration is now low priority.

🚀 Development Setup

Quick Start

git clone https://github.com/Imperialorg/folktheory.git
cd folktheory
pnpm install
cp .env.example .env.local   # create if missing; see vars below
pnpm dev

Visit: http://localhost:3000

Prerequisites

Installation

# Clone repository
git clone https://github.com/Imperialorg/folktheory.git
cd folktheory

# Install dependencies
pnpm install

# Configure environment
cp .env.example .env.local
# Edit .env.local with your configurations

# Set up database indexes (optional but recommended)
npx tsx scripts/setup-messaging-indexes.ts

# Run tests (optional)
pnpm test

# Run type check (optional)
npx tsc --noEmit

Available Scripts

# Development
pnpm dev              # Start development server with Turbopack
pnpm build            # Build for production
pnpm build:turbo      # Build with Turbopack (2-5x faster)
pnpm start            # Start production server
pnpm lint             # Run ESLint
pnpm test             # Run tests with Vitest
pnpm test:ui          # Run tests with UI
pnpm test:coverage    # Generate coverage report

Test Redis connection

npx tsx scripts/test-redis-connection.ts

Run development server

pnpm dev


### Environment Variables

See `.env.example` for the authoritative list. Summary:

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| NEXTAUTH_URL | Yes (prod) | <http://localhost:3000> | Public base URL for auth callbacks |
| NEXTAUTH_SECRET | Yes | — | 32+ byte secret for JWT/session encryption |
| MONGODB_URI | Yes | — | MongoDB connection string |
| REDIS_HOST | Yes (if Redis) | — | Redis endpoint hostname |
| REDIS_PORT | No | 6380 | Redis port (TLS) |
| REDIS_PASSWORD | Yes (if Redis) | — | Redis auth password |
| REDIS_TLS | No | true | Enable TLS connection |
| REDIS_CA_PATH | No | ./app/rackspace-ca-2021.pem | CA cert for TLS |
| NEXT_PUBLIC_ABLY_KEY | Yes | — | Ably API key for real-time messaging |
| R2_ENDPOINT | Yes (if R2) | — | Cloudflare R2 S3-compatible endpoint |
| R2_ACCESS_KEY_ID | Yes (if R2) | — | R2 access key |
| R2_SECRET_ACCESS_KEY | Yes (if R2) | — | R2 secret key |
| R2_BUCKET_NAME | Yes (if R2) | folktheory | Asset bucket name |
| R2_PUBLIC_URL | No | <https://assets.folktheory.dev> | Public CDN/base URL |
| FASTLY_OS_ENDPOINT | No | — | Fastly Object Storage endpoint (failover) |
| FASTLY_OS_REGION | No | us-east | Fastly OS region |
| FASTLY_OS_BUCKET | No | — | Fastly OS bucket name |
| FASTLY_OS_ACCESS_KEY_ID | No | — | Fastly OS access key |
| FASTLY_OS_SECRET_ACCESS_KEY | No | — | Fastly OS secret key |
| AWS_ACCESS_KEY_ID | Conditional | — | AWS key if using AWS services directly |
| AWS_SECRET_ACCESS_KEY | Conditional | — | AWS secret if using AWS services |
| CALLS_APP_ID | Yes (if video) | — | Cloudflare Calls application ID |
| CALLS_APP_SECRET | Yes (if video) | — | Cloudflare Calls API secret |
| ENABLE_DEMO_ENDPOINTS | No | false | Expose /api/demo/* endpoints (disabled in prod) |
| ENABLE_DEBUG_ENDPOINTS | No | false | Expose /api/debug* endpoints (disabled in prod) |

> Tip: copy `.env.example` to `.env.local` and fill in required secrets before running `pnpm dev`. Demo/debug endpoint flags are off by default; only enable temporarily when needed.

### Performance Optimization

#### Next.js 15.5.9 Performance Features

- **Turbopack Production Builds**: Available with `pnpm build --turbopack` (2-5x faster builds)
- **TypeScript Typed Routes**: Compile-time route validation prevents broken links
- **Node.js Middleware**: Full Node.js API access for enhanced middleware capabilities
- **Auto-Generated Types**: PageProps, LayoutProps, and RouteContext automatically typed

#### Application Performance

**Redis 7.2.5 Optimizations:**

```bash
# Test Redis 7.2.5 performance improvements
npx tsx scripts/test-redis-optimizations.js

# Test admin cache with Redis 7.2.5 features
npx tsx scripts/test-admin-cache.js

# Monitor Redis health and memory
npx tsx scripts/test-redis-connection.ts

Performance Results:

Monitoring & Observability:

Code Quality:

# Run tests
pnpm test

# Run tests with UI
pnpm test:ui

# Generate coverage report
pnpm test:coverage

# Type check
npx tsc --noEmit

# Lint code
pnpm lint

⚠️ Security Note: Credentials are currently hard-coded in lib/mongodb.ts and lib/redis-client.ts for development convenience. Before any production deployment:

  1. Move all secrets into environment variables (or a secret manager).
  2. Rotate the exposed credentials immediately.
  3. Add a .env.example file enumerating required keys (without values).
  4. Add automated secret scanning (GitHub Advanced Security / gitleaks) in CI.
  5. Strengthen NEXTAUTH_SECRET (min 32+ random bytes).

📊 Platform Metrics & Goals

Current Status

Recent Performance Achievements

Success Metrics

🚀 Deployment

Production Deployment

Platform: Vercel (Auto-deploy from Git)
Project: folktheory

Deployment Configuration

Features Available in Production

✅ Redis 7.2.5 Optimizations - Auto-pipelining and enhanced TLS
✅ Real-time Admin Dashboard - Redis memory monitoring
✅ MongoDB 7.0.20 Statistics - Database health monitoring
✅ Enterprise Messaging - Redis pub/sub real-time updates
✅ Cloudflare Calls - WebRTC voice/video (330+ edge locations)
✅ Performance Optimized UI - Smooth operation without GPU strain
✅ Theme System - Light/Dark/System mode switching

Local Development

# Start development server
pnpm dev

# Access locally
http://localhost:3000

🤝 Contributing

Development Workflow

  1. Fork the repository
  2. Create feature branch (git checkout -b feature/amazing-feature)
  3. Commit changes (git commit -m 'Add amazing feature')
  4. Push to branch (git push origin feature/amazing-feature)
  5. Open Pull Request

Code Standards

Performance Testing

# Test Redis messaging performance
npx tsx scripts/test-messaging-performance.ts

# Debug message cache
npx tsx scripts/debug-message-cache.js

# Test Redis connection
npx tsx scripts/test-redis-connection.ts

🧱 High-Level Architecture

┌──────────────────────────┐
│        Next.js App       │  (App Router + React 19)
│  UI / API Routes / SSR   │
└────────────┬─────────────┘
         │
  Auth (NextAuth.js) ─────────► JWT sessions / middleware protection
         │
  MongoDB 7.0.20 ─────────────► Primary persistence (Users, Startups, Messages, Notifications)
         │
  Redis 7.2.5 ────────────────► Caching, pub/sub, rate limits (Auto-pipelining + Enhanced TLS)
         │
  Ably Realtime ──────────────► WebSocket real-time messaging (6M msg/month free)
         │
  Cloudflare Calls ───────────► WebRTC voice/video (Global SFU, 330+ edges)
         │
  Cloudflare R2 (Primary) ────► File & asset storage (S3-compatible, public CDN)
         │
  Fastly Object Storage ──────► Backup file storage (automatic failover)
         │
  Vercel ─────────────────────► Production deployment + serverless functions

Messaging Data Flow

  1. User sends message in browser
  2. WebSocket message via Ably client → Ably edge network
  3. Server receives via Ably webhook/REST API
  4. Persist to MongoDB 7.0.20
  5. Update Redis 7.2.5 cache (with auto-pipelining)
  6. Publish to Ably channel (server-side)
  7. Ably broadcasts to all subscribed clients instantly
  8. Recipients receive message in real-time (0-latency)
  9. Subsequent reads served from Redis (fallback to MongoDB on miss)

Project Structure

├── app/                    # Next.js App Router
│   ├── admin/             # Admin dashboard with Redis/MongoDB monitoring
│   ├── api/               # API routes including cache-health endpoints
│   │   ├── auth/         # Authentication endpoints
│   │   ├── messages/     # Messaging API
│   │   ├── upload/       # File upload endpoints
│   │   └── media/        # Media proxy (Fastly failover)
│   ├── messages/         # Messaging UI
│   └── ...               # Other app pages
├── components/            # React components
│   ├── redis-monitor.tsx  # Redis 7.2.5 memory monitoring
│   ├── mongo-monitor.tsx  # MongoDB 7.0.20 statistics
│   └── ...                # Other UI components
├── lib/                   # Core libraries
│   ├── admin-cache.ts     # Redis 7.2.5 admin caching system
│   ├── redis-client.ts    # Enhanced Redis client with auto-pipelining
│   ├── mongodb.ts         # MongoDB 7.0.20 connection
│   ├── services/         # Service layer
│   │   ├── messaging-service.ts  # Messaging logic
│   │   ├── r2-file-service.ts    # File storage
│   │   └── ...           # Other services
│   └── ...               # Other utilities
├── fastly-compute/        # Fastly Compute@Edge (Rust/WASM)
│   ├── src/              # Rust source code
│   │   ├── main.rs       # Entry point and routing (356 lines)
│   │   ├── auth.rs       # JWT authentication
│   │   ├── rate_limit.rs # Rate limiting
│   │   ├── cache.rs      # Caching layer
│   │   ├── media.rs      # Media serving
│   │   └── presigned.rs  # S3 presigned URLs
│   ├── pkg/              # Compiled WASM packages
│   │   └── package.tar.gz # Deployed version (753KB WASM)
│   ├── fastly.toml       # Service configuration
│   ├── Cargo.toml        # Rust dependencies
│   ├── DEPLOYMENT.md     # Deployment guide
│   └── README.md         # Development guide
├── docs/                  # Documentation
│   ├── FASTLY_ROUTING_MYSTERY.md  # Current blocking issue
│   ├── FASTLY_DEPLOYMENT_STATUS.md # Deployment status
│   ├── EDGE_COMPUTING_LAYER_GATE_ANALYSIS.md
│   ├── REDIS_725_OPTIMIZATIONS.md
│   └── ...               # Other documentation
└── scripts/               # Development and testing scripts
    ├── test-redis-optimizations.js
    ├── test-admin-cache.js
    ├── test-fastly-websockets.js
    └── ...                # Other scripts

Last Updated: 14th of December 2025
Platform Version: 0.3.1
Next.js Version: 15.5.9
React Version: 19.2.0
MongoDB Version: 7.0.20
Redis Version: 7.2.5 (with auto-pipelining optimizations)
Ably Version: 2.15.0 (WebSocket real-time messaging)
Mongoose Version: 8.16.4
IORedis Version: 5.8.2
Major Updates: Next.js 15.5.9 upgrade, Fastly Compute@Edge deployment, Ably real-time integration, Fastly Object Storage failover, multi-cloud architecture, enhanced UX

License

MIT — see LICENSE (add one if missing).