Architecture Overview

High-Level System Architecture

Jubiloop is a pragmatic full-stack application built as a monorepo, designed with cost-effectiveness, simplicity, and developer experience in mind. The system follows a monolithic architecture with clear boundaries, ready to evolve as our needs grow.

Philosophy: Pragmatic architecture with clear growth paths. Every decision is optimized for today while ensuring smooth scaling tomorrow. See our Infrastructure Philosophy for details.

For the complete list of technologies and versions, see the Technology Stack Reference.

System Architecture Diagrams

Development/QA Environment (Shared Infrastructure)

┌─────────────────────────────────────────────────────────────┐
│                    Cloudflare                                │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐ │
│  │ Cloudflare Pages│  │ Cloudflare Pages│  │   DNS/CDN   │ │
│  │ (Dev Web App)   │  │ (QA Web App)    │  │             │ │
│  └─────────────────┘  └─────────────────┘  └─────────────┘ │
└───────────────────────────┬─────────────────────────────────┘
                            │ API Requests
┌───────────────────────────▼─────────────────────────────────┐
│         DigitalOcean Droplet ($6/month)                      │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              Docker Containers                       │    │
│  │  ┌─────────────────┐  ┌─────────────────┐          │    │
│  │  │   Caddy Proxy   │  │   Caddy Proxy   │          │    │
│  │  │  (dev.domain)   │  │  (qa.domain)    │          │    │
│  │  └────────┬────────┘  └────────┬────────┘          │    │
│  │           │                     │                    │    │
│  │  ┌────────▼────────┐  ┌────────▼────────┐          │    │
│  │  │  Dev API Server │  │  QA API Server  │          │    │
│  │  │   (Port 3333)   │  │   (Port 3334)   │          │    │
│  │  └────────┬────────┘  └────────┬────────┘          │    │
│  │           │                     │                    │    │
│  │  ┌────────▼──────────────────────────────┐         │    │
│  │  │         Database Services              │         │    │
│  │  │  ┌─────────┐  ┌─────────┐  ┌────────┐│         │    │
│  │  │  │Postgres │  │Postgres │  │ Redis  ││         │    │
│  │  │  │  (Dev)  │  │  (QA)   │  │ (Dev)  ││         │    │
│  │  │  └─────────┘  └─────────┘  └────────┘│         │    │
│  │  │              ┌────────┐                │         │    │
│  │  │              │ Redis  │                │         │    │
│  │  │              │  (QA)  │                │         │    │
│  │  │              └────────┘                │         │    │
│  │  └───────────────────────────────────────┘         │    │
│  └─────────────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────────────┘

Production Environment (Dedicated Infrastructure)

┌─────────────────────────────────────────────────────────────┐
│                    Cloudflare                                │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐ │
│  │ Cloudflare Pages│  │ Cloudflare Pages│  │   DNS/CDN   │ │
│  │ (Prod Web App)  │  │ (Prod Marketing)│  │             │ │
│  └─────────────────┘  └─────────────────┘  └─────────────┘ │
└───────────────────────────┬─────────────────────────────────┘
                            │ API Requests
┌───────────────────────────▼─────────────────────────────────┐
│         DigitalOcean Droplet ($6/month)                      │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              Docker Containers                       │    │
│  │  ┌─────────────────────────────────────────┐       │    │
│  │  │            Caddy Proxy                   │       │    │
│  │  │         (api.jubiloop.ca)               │       │    │
│  │  └────────────────┬─────────────────────────┘       │    │
│  │                   │                                  │    │
│  │  ┌────────────────▼─────────────────────────┐       │    │
│  │  │         Production API Server            │       │    │
│  │  │            (Port 3333)                   │       │    │
│  │  └────────────────┬─────────────────────────┘       │    │
│  │                   │                                  │    │
│  │  ┌────────────────▼─────────────────────────┐       │    │
│  │  │              Redis Cache                 │       │    │
│  │  └──────────────────────────────────────────┘       │    │
│  └─────────────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────────────┘
                            │
                            │ Database Connection
┌───────────────────────────▼─────────────────────────────────┐
│                    Neon Database                             │
│                 (Managed PostgreSQL)                         │
│               Region: US East (Ohio)                         │
└──────────────────────────────────────────────────────────────┘

Main Components

Frontend Applications

1. Web Application (apps/webapp/)

   • React SPA for authenticated users
   • File-based routing with TanStack Router
   • Client-side state management with Zustand

2. Marketing Site (apps/marketing/)

   • Next.js for SEO-optimized public pages
   • Static site generation
   • Interactive feature demonstrations

Backend Services

API Server (apps/server/)

• AdonisJS for batteries-included backend
• RESTful API
• Session-based authentication
• Comprehensive data validation

Data Layer

1. PostgreSQL Database

   • Primary data store
   • Managed migrations
   • Development: Docker container
   • Production: Neon managed service

2. Redis Cache

   • Session storage
   • Application caching
   • Performance optimization

Infrastructure Components

1. Reverse Proxy (Caddy)

   • HTTPS termination with automatic certificates
   • Load balancing capabilities
   • Request routing to different services
   • Security headers management

2. Container Orchestration

   • Docker Compose for local development
   • Production-ready Docker images
   • Environment-specific configurations

Technology Choices and Rationale

Core Technologies

1. TypeScript

   • Why: Type safety across the entire stack reduces runtime errors and improves developer experience
   • Centralized type definitions via @jubiloop/shared-types package
   • Better IDE support and refactoring capabilities
   • Consistent naming conventions (I-prefix for interfaces, T-prefix for types)

2. Turborepo

   • Why: Efficient monorepo management with intelligent caching
   • Parallel task execution
   • Dependency graph optimization
   • Simplified CI/CD pipelines

3. React + Vite

   • Why: Fast development experience with hot module replacement
   • Modern build tooling with optimal bundle sizes
   • Large ecosystem and community support
   • Component-based architecture for reusability

4. Next.js (Marketing)

   • Why: SEO optimization crucial for marketing sites
   • Built-in performance optimizations
   • Image optimization and lazy loading
   • Static generation capabilities

5. AdonisJS

   • Why: Batteries-included framework reduces boilerplate
   • Built-in authentication and security features
   • Excellent TypeScript support
   • Active Record ORM pattern for rapid development

6. PostgreSQL

   • Why: Robust, ACID-compliant relational database
   • JSON support for flexible data structures
   • Excellent performance and scalability
   • Strong consistency guarantees
   • UUID v7 for primary keys provides better index performance

7. Redis

   • Why: High-performance caching layer
   • Session management at scale
   • Pub/sub capabilities for real-time features
   • Low latency data access

Type System Architecture

Shared Types Package (@jubiloop/shared-types)

• Why: Single source of truth for type definitions
• Eliminates duplicate type definitions between frontend and backend
• Wildcard exports avoid barrel export issues
• Two-tier build process:
  • Production: No source maps for security
  • Development: Declaration maps for IDE navigation
• Organized structure:
  • entities/ - Core domain models
  • dtos/ - Data Transfer Objects
  • api/responses/ - API response types
  • api/requests/ - API request types

Development Tools

1. shadcn/ui + Tailwind CSS

   • Why: Rapid UI development with consistent design system
   • Copy-paste component architecture
   • Full customization capabilities
   • Accessible by default

2. Vitest

   • Why: Fast unit testing with Vite integration
   • Compatible with Jest API
   • Native ESM support
   • Snapshot testing capabilities

3. ESLint + Prettier

   • Why: Consistent code style across the monorepo
   • Automated code quality checks
   • Git hooks integration with Husky
   • Shared configuration packages

System Architecture Diagram

┌─────────────────────────────────────────────────────────────────┐
│                        Load Balancer / CDN                       │
└─────────────────────┬───────────────────┬───────────────────────┘
                      │                   │
              ┌───────▼────────┐  ┌───────▼────────┐
              │  Marketing Site │  │   Web App      │
              │   (Next.js)     │  │   (React)      │
              └───────┬────────┘  └───────┬────────┘
                      │                   │
┌─────────────────────▼───────────────────▼───────────────────────┐
│                    Reverse Proxy (Caddy)                         │
│                    - HTTPS Termination                           │
│                    - Request Routing                             │
└─────────────────────────────┬───────────────────────────────────┘
                              │
                     ┌────────▼────────┐
                     │   API Server    │
                     │   (AdonisJS)    │
                     └────┬───────┬────┘
                          │       │
                ┌─────────▼───┐ ┌─▼──────────┐
                │ PostgreSQL  │ │   Redis    │
                │  Database   │ │   Cache    │
                └─────────────┘ └────────────┘

Security Considerations

• HTTPS everywhere with automatic certificate management
• Authentication and authorization at API level
• CORS configuration for cross-origin requests
• SQL injection prevention through ORM
• XSS protection with React's built-in escaping
• Environment variable management for secrets
• Regular security updates through automated workflows

Performance Optimization

• Client-side code splitting and lazy loading
• Server-side caching with Redis
• Database query optimization
• CDN integration for static assets
• Image optimization in marketing site
• Efficient build pipeline with Turborepo caching

Related Documentation

• Monorepo Structure - Detailed breakdown of the project structure
• Deployment Overview - Infrastructure and deployment architecture
• Data Models - Database schema and relationships