Skip to main content

System Architecture

CivStart uses a modern, cloud-native architecture deployed on AWS with serverless components.

High-Level Architecture​

┌─────────────────────────────────────────────────────────────────┐
│                         Cloudflare DNS                          │
└──────────────┬──────────────────────────────────┬───────────────┘
               │                                  │
       ┌───────▼────────┐                ┌───────▼────────┐
       │ Vercel (CDN)   │                │   AWS NLB      │
       │                │                │   (TCP/TLS)    │
       │ - Frontend     │                └───────┬────────┘
       │ - Admin Portal │                        │
       └────────────────┘                ┌───────▼────────┐
                                         │   ECS Fargate  │
                                         │                │
                                         │  Backend API   │
                                         │  + WebSockets  │
                                         └───┬────────┬───┘
                                             │        │
                                    ┌────────▼─┐  ┌──▼──────────┐
                                    │   RDS    │  │ ElastiCache │
                                    │Postgres  │  │    Redis    │
                                    └──────────┘  └─────────────┘

Components​

Frontend (Vercel)​

  • Next.js 15 with App Router
  • React 19 for UI components
  • Tailwind CSS + shadcn/ui for styling
  • Clerk for authentication
  • Socket.IO Client for real-time updates

Admin Portal (Vercel)​

  • Separate Next.js application
  • Admin-specific Clerk instance
  • Administrative functions and dashboards

Backend API (AWS ECS)​

  • NestJS 11 REST API
  • Socket.IO WebSocket server
  • Prisma ORM for database access
  • Google Gemini AI for matching
  • Pinecone for vector embeddings

Database (AWS RDS)​

  • PostgreSQL 15
  • Private subnet (secure)
  • Multi-AZ for production
  • Automated backups

Cache (AWS ElastiCache)​

  • Redis 7
  • Session storage
  • API response caching
  • WebSocket connection state

Load Balancer (AWS NLB)​

  • Layer 4 (TCP/TLS) load balancing
  • Supports WebSocket protocol
  • SSL/TLS termination
  • Health checks

Infrastructure (Terraform)​

  • Infrastructure as Code
  • Separate workspaces per environment
  • Modular architecture
  • State stored in S3

Data Flow​

Authentication Flow​

  1. User accesses frontend (civstart.ventures)
  2. Clerk handles authentication
  3. JWT token issued to client
  4. Token passed to backend API
  5. Backend validates with Clerk

WebSocket Flow​

  1. Client connects to API endpoint
  2. NLB routes to ECS container
  3. Socket.IO handshake established
  4. Client subscribes to rooms (e.g., startup:${id})
  5. Real-time updates pushed to subscribed clients

Matching Flow​

  1. New signal created in database
  2. Signal vectorized using Gemini AI
  3. Vector stored in Pinecone
  4. Similarity search against startup vectors
  5. Match suggestions created
  6. WebSocket notification sent to matched startups

Security​

Network Security​

  • Backend in private subnets
  • RDS in private subnets
  • Security groups restrict access
  • NLB handles TLS termination

Application Security​

  • Clerk authentication
  • JWT validation
  • Rate limiting
  • Input validation

Data Security​

  • Encrypted at rest (RDS)
  • Encrypted in transit (TLS)
  • Secrets in AWS Secrets Manager
  • No plaintext credentials

Scalability​

Horizontal Scaling​

  • ECS Fargate auto-scaling
  • Read replicas for RDS
  • ElastiCache cluster mode

Caching Strategy​

  • Redis for API responses
  • CloudFront CDN for static assets
  • Database query optimization

Monitoring​

Logging​

  • CloudWatch Logs for all services
  • Structured logging
  • Log retention policies

Metrics​

  • CloudWatch Metrics
  • ECS task metrics
  • RDS performance metrics
  • Custom application metrics

Alerts​

  • CloudWatch Alarms
  • SNS notifications
  • On-call rotation

Deployment​

See Deployment Documentation for detailed deployment instructions.