Hagglz Technical Architecture Documentation

Version 2.0 | October 2025

Executive Summary

Hagglz is a TypeScript-first monorepo architected for multi-platform bill negotiation with a strategic focus on web-to-mobile conversion. Built on modern React ecosystem with full-stack type safety and shared business logic, the platform leverages AI-powered negotiation through advanced API integration and real-time communication.

Architecture Overview

Platform Strategy & Repository Structure

hagglz-v2/ (Turborepo Monorepo)
├── apps/
│   ├── web/           # Next.js 15.1.7 - Marketing & Lead Generation
│   └── mobile/        # React Native + Expo 52 - Core Platform
├── packages/          # Shared Libraries (@repo/[name])
│   ├── api/           # Hono.js API Server + OpenAPI
│   ├── database/      # Prisma ORM + PostgreSQL
│   ├── auth/          # Better-auth + Clerk Integration
│   ├── ui-native/     # React Native Components
│   ├── payments/      # Stripe + RevenueCat
│   ├── storage/       # AWS S3 File Management
│   ├── mail/          # Multi-provider Email
│   ├── i18n/          # Internationalization (en/de)
│   ├── logs/          # Structured Logging
│   ├── ai/            # AI Integration Layer
│   └── utils/         # Cross-platform Utilities
└── tooling/           # Development Tools & Config
    ├── tailwind/      # Shared Design System
    ├── typescript/    # TS Configurations
    └── scripts/       # Build & Deploy Scripts

Multi-Platform Architecture

graph TB
    subgraph "Client Applications"
        WEB["Web App (Next.js 15)"]
        MOBILE["Mobile App (React Native + Expo)"]
    end

    subgraph "API Layer"
        API["Hono.js API Server"]
        OPENAPI["OpenAPI Documentation"]
        WS["WebSocket Server"]
    end

    subgraph "Shared Packages (@repo/*)"
        DB["Database (Prisma)"]
        AUTH["Auth (Better-auth + Clerk)"]
        PAY["Payments (Stripe + RevenueCat)"]
        STORE["Storage (AWS S3)"]
        MAIL["Mail (Multi-provider)"]
        AI_PKG["AI (OpenAI + Claude)"]
    end

    subgraph "Infrastructure"
        PG[("PostgreSQL")]
        REDIS[("Redis")]
        S3[("AWS S3")]
        SUPABASE["Supabase (Realtime)"]  
    end

    WEB --> API
    MOBILE --> API
    API --> OPENAPI
    API --> WS
    
    API --> DB
    API --> AUTH
    API --> PAY
    API --> STORE
    API --> MAIL
    API --> AI_PKG
    
    DB --> PG
    AUTH --> REDIS
    STORE --> S3
    DB --> SUPABASE

Technology Stack

Core Framework & Runtime

Component	Technology	Version	Purpose
Monorepo	Turborepo + pnpm	^2.4.4	Build orchestration & dependency management
Package Manager	pnpm	9.3.0	Fast, efficient package management
Runtime	Node.js	≥20 LTS	JavaScript runtime
TypeScript	TypeScript	5.8.2	Type-safe development
Environment	dotenv-cli	^8.0.0	Environment variable management

Frontend Technologies

Web Application (Marketing & Onboarding)

Component	Technology	Version	Purpose
Framework	Next.js	15.1.7	React framework with App Router
React	React	19.0.0	UI library
Styling	Tailwind CSS	4.0.12	Utility-first CSS
UI Components	Shadcn UI + Radix UI	Latest	Component library
Routing	Next.js App Router	Built-in	File-based routing
State Management	Nuqs	^2.4.0	URL-based state management
Internationalization	Next-intl	3.26.5	Multi-language support (en/de)
Content	Content Collections + MDX	^0.8.2	Blog & documentation
Analytics	Multiple Providers	-	Google, Mixpanel, Plausible, PostHog
Testing	Playwright	^1.51.0	End-to-end testing

Mobile Application (Core Platform)

Component	Technology	Version	Purpose
Framework	React Native	0.77.3	Cross-platform mobile
Expo SDK	Expo	~52.0.0	Mobile development platform
Navigation	Expo Router	~4.0.0	File-based mobile routing
Authentication	Clerk Expo	^2.8.23	Mobile auth integration
Animations	Reanimated	~3.16.1	Native animations
Storage	AsyncStorage	1.24.0	Local data persistence
Camera	Expo Camera	~16.0.6	Bill scanning capability
Image Processing	Expo Image Manipulator	~12.0.5	Image optimization