Aruuri Monorepo Architecture

Aruuri is built as a monorepo to foster transparent community funding, leveraging a sophisticated architecture designed for scalability, maintainability, and clear separation of concerns. This structure is powered by Turborepo↗ for efficient build orchestration and pnpm↗ for package management, following domain-driven design principles with functional programming patterns. For an overview of the platform's mission and purpose, refer to the [Aruuri Platform Overview] page.

Monorepo Structure

The codebase is organized into two main top-level directories: apps/ for independent deployable applications and packages/ for shared, reusable code.

aruuri/
├── apps/
│   ├── web/                 # Next.js public web app (App Router)
│   ├── cms/                 # Payload CMS (future, subdomain)
│   └── functions/           # AWS Lambda functions (future, webhooks/cron)
└── packages/
    ├── services/            # Vendor-agnostic services (email, storage, payments)
    ├── domain/              # Business logic (pure functions, immutable)
    ├── database/            # Drizzle ORM for Neon PostgreSQL
    ├── design-tokens/       # Design tokens from Figma → CSS variables
    └── utils/               # Shared utilities (date, currency, format)

apps/ Directory

This directory contains independently deployable applications, each representing a distinct part of the Aruuri platform:

• web/: The main public-facing web application. It's built with Next.js (utilizing the App Router), React, Tailwind CSS v4, and Radix UI. This is where users interact with the platform, contribute, and track impact.
• cms/: Planned for a future subdomain, this will house the Payload CMS instance, managing content, media, and other administrative data.
• functions/: Reserved for future AWS Lambda functions. These serverless functions will handle various backend tasks such as webhooks, cron jobs, and specific API endpoints, providing a scalable and cost-effective approach for real-time operations.

packages/ Directory

This directory is home to shared code and components that can be consumed by multiple applications within the monorepo, ensuring consistency and reusability:

• services/: This package abstracts external vendor integrations (e.g., email, storage, payments). Its vendor-agnostic design allows for switching providers (e.g., from Resend to SendGrid) without requiring changes in the application-level code.
• domain/: Contains the core business logic of the Aruuri platform. It adheres to functional programming patterns, emphasizing pure functions and immutability, making the logic predictable and testable.
• database/: Provides the shared database layer using Drizzle ORM for Neon PostgreSQL. This package encapsulates schema definitions, migration scripts, and client configurations, ensuring type-safe interactions with the multi-domain database setup. Detailed information can be found in packages/database/README.md.
• design-tokens/: Houses the centralized design tokens, which are exported from Figma and transformed into CSS variables and JavaScript constants using Style Dictionary. This ensures a single source of truth for design language across the platform. Refer to docs/FIGMA_TOKENS.md for its workflow.
• utils/: A collection of shared utility functions, including helpers for date formatting, currency conversions (minor to major units and vice-versa), number formatting, and string manipulation like slugification.

Key Architectural Principles

The Aruuri architecture is founded on several core principles:

• Apps as Independent Deployments: Each application in the apps/ directory is designed to be independently deployable, allowing for flexible scaling and deployment strategies for the web app, CMS, and serverless functions.
• Packages for Shared Code: The packages/ directory ensures that common functionalities and UI components are centralized and reusable, reducing redundancy and promoting consistency.
• Vendor-Agnostic Services: External service integrations are abstracted behind a generic interface within the services/ package. This minimizes coupling to specific third-party providers, making it easier to swap services without affecting business logic.
• Functional-First Approach: Emphasizes pure functions, immutability, and composability, leading to more predictable, testable, and maintainable code.
• Type-Safe Development: Strong TypeScript typing is enforced across the entire codebase, catching potential errors early in development and improving code clarity and reliability.

For more in-depth architectural guidance, refer to docs/ARCHITECTURE.md.

High-Level Tech Stack

Aruuri leverages a modern and robust tech stack to deliver a high-performance, transparent, and user-friendly platform:

• Frontend: Next.js 15.5, React 19, Tailwind CSS v4 for styling.
• Design System: Radix UI for accessible primitives, shadcn/ui v4 for components, CVA (Class Variance Authority) for variant management, and Storybook v9 for component documentation and testing.
• Database: Drizzle ORM for type-safe database interactions with Neon PostgreSQL as the serverless relational database.
• Build Tools: tsdown for utility packages, Next.js for the main application, and Turborepo for monorepo orchestration.
• Type Safety: TypeScript 5.9 and Zod schemas for robust data validation.
• Package Management: pnpm for efficient dependency management and Turborepo for optimized monorepo performance.
• Design Tokens: Figma Variables integrated with Style Dictionary to generate design tokens for the shadcn Theme.