Ivyi Platform Architecture

📑 Table of Contents

• 📖 Overview
• 🏗️ Overall Architecture
• 📁 Directory Structure
• 🎯 Core Technologies
• 🔄 Data Flow
• 📦 Shared Packages
• 🔧 Development Tools

Core Documentation

• 📖 Architecture Overview - This page - Complete system design guide
• 🏗️ API Architecture - Backend system design and component interactions
• �️ Database Architecture - PostgreSQL database design and Drizzle ORM integration
• �🚀 Queues & Jobs - PgBoss-powered queue system and background processing
• 👷 Workers & Events - Background workers and event-driven architecture

📖 Overview

Ivyi is a revolutionary gifting platform built with modern, scalable architecture following domain-driven design principles. The platform consists of backend API services and frontend web applications that work together to provide seamless celebration and gifting experiences.

🏗️ Overall Architecture

1. Domain-Driven Design: Clear separation of concerns across business domains
2. Microservices Approach: Independent backend and frontend services
3. Type Safety: End-to-end TypeScript integration
4. API-First: Backend services designed as APIs first
5. Modern Tooling: Latest development tools and practices

Monorepo Organization

Ivyi/
├── apps/                    # Application services
│   ├── api/                 # Backend API service
│   └── web/                 # Frontend web application
├── packages/                 # Shared packages
│   ├── eslint-config/         # ESLint configurations
│   ├── typescript-config/     # TypeScript configurations
│   └── ui/                  # Shared UI components
├── docs/                     # Platform documentation
├── architecture.md             # This file
├── README.md                  # Platform overview
├── package.json               # Root package configuration
├── turbo.json                 # Turborepo configuration
└── .gitignore                 # Git ignore rules

Application Structure

Backend API (apps/api/)

• config/ - Application and server configuration
• feature/ - Domain-specific modules (users, occasions, etc.)
• lib/ - External packages and shared utilities
• middleware/ - Express middleware functions
• routes/ - API route definitions
• utils/ - General utility functions

Frontend Web (apps/web/)

• app/ - React Router application
• components/ - Shared UI components
• feature/ - Domain-specific components
• lib/ - API clients and utilities
• routes/ - Route definitions

🎯 Core Technologies

Backend Stack

• Runtime: Node.js 20+
• Framework: Express.js with TypeScript
• Database: PostgreSQL with Drizzle ORM
• Authentication: JWT-based with role-based access
• API Documentation: OpenAPI/Swagger with interactive UI
• Validation: Zod schemas for request/response validation
• Security: Rate limiting, CORS, security headers

Frontend Stack

• Framework: React Router with TypeScript
• Styling: TailwindCSS for utility-first styling
• Build Tool: Vite for fast development and building
• State Management: React Router's built-in data loading
• Type Safety: End-to-end TypeScript integration

Shared Infrastructure

• Package Manager: npm/yarn with Turborepo for monorepo management
• Code Quality: ESLint, Prettier, TypeScript for consistent code
• Development: Hot Module Replacement, fast refresh cycles
• Documentation: Comprehensive API and platform documentation

🔄 Data Flow

Data Flow Patterns

1. User Interactions: Web actions → API requests → Database operations
2. Real-time Updates: WebSocket connections and SSEs for live updates
3. Event-Driven: Domain events for cross-system communication
4. Caching Strategy: Multi-layer caching for performance

📦 Shared Packages

The platform uses a monorepo structure with shared packages that promote code reuse and consistency across applications:

Package Management Strategy

packages/
├── ui/                  # Shared React component library
├── eslint-config/         # ESLint configurations
├── typescript-config/     # TypeScript configurations
└── lib/                  # Shared functionality and 3rd party libraries

@ivyi/ui

• Purpose: Shared React component library for consistent UI across applications
• Usage: Imported by both web app and future applications
• Technologies: React, TypeScript, TailwindCSS
• Features:
  • Design system components (buttons, forms, layouts)
  • Reusable business components (gift cards, user profiles)
  • Consistent styling and theming
  • Accessibility-first implementation
• Benefits: Single source of truth for UI, consistent user experience

@ivyi/lib

• Purpose: Shared functionality and third-party library integrations
• Contents:
  • Database utilities and connection helpers
  • API client functions and HTTP utilities
  • Validation schemas and shared types
  • Logging and error handling utilities
  • Business logic helpers (date formatting, etc.)
• Benefits: Code reuse, consistent behavior, easier maintenance

@ivyi/eslint-config

• Purpose: ESLint configurations for consistent code quality across all packages
• Includes:
  • Base ESLint configuration
  • Next.js specific rules
  • Prettier integration for formatting
  • TypeScript-specific linting rules
• Enforcement: Automated linting in CI/CD pipeline
• Benefits: Consistent code style, fewer bugs, better developer experience

@ivyi/typescript-config

• Purpose: TypeScript configurations for type safety across the monorepo
• Includes:
  • Base TypeScript configuration
  • Next.js optimized compiler options
  • Path mapping for clean imports
  • Strict type checking enabled
• Benefits: Type safety, better IDE support, catch errors early

Monorepo Benefits

1. Code Sharing: Shared packages eliminate duplication
2. Consistent Dependencies: Single source of truth for versions
3. Unified Tooling: Same linting, formatting, build tools across all packages
4. Atomic Commits: Changes tracked per package, better change management
5. Scalable Structure: Easy to add new applications or shared packages
6. Independent Development: Teams can work on different packages simultaneously

Package Dependencies

apps/api/     → @ivyi/ui (for admin interfaces)
               → @ivyi/lib (shared utilities)
               → @ivyi/eslint-config
               → @ivyi/typescript-config

apps/web/     → @ivyi/ui (component library)
               → @ivyi/lib (API clients)
               → @ivyi/eslint-config
               → @ivyi/typescript-config

Development Workflow

1. Root-level Commands: Turborepo manages dependencies and scripts across packages
2. Shared Changes: Made in individual packages, versioned independently
3. Cross-package Testing: Integration tests ensure compatibility
4. Consistent Releases: All packages versioned and released together

🔧 Development Tools

Code Quality Stack

• TypeScript: Static type checking across all packages
• ESLint: Code linting with consistent rules
• Prettier: Code formatting for consistency
• Husky: Git hooks for pre-commit checks
• Commitizen: Standardized commit messages