Arda Platform Monorepo

A Turborepo-based monorepo housing the complete Arda fintech platform ecosystem.

About Arda

Arda is a comprehensive fintech platform that connects institutional investors with loan originators, facilitating investment opportunities and secure document management through a suite of integrated applications.

What's Inside?

This monorepo contains three main applications that work together to provide a complete investment platform experience:

Applications

🔐 Platform (@arda/platform)

Central authentication and company management portal - Port 3002

The gateway to the Arda ecosystem. Handles:

• Passwordless magic link authentication
• Company creation and management (originators & investors)
• Team member invitations and role-based access
• Routing users to appropriate applications with secure token handoff

Key Features:

• Magic link email authentication (15-minute expiration)
• Dual company types: Originator (deal creators) and Investor (deal reviewers)
• Seamless SSO across all Arda applications
• Invitation-based team member onboarding

View Platform Documentation →

💰 Credit App (@arda/credit-app)

Investor-originator matching and investment platform - Port 3000

Connects institutional investors with loan originators for investment opportunities. Features:

• AI-powered deal matching algorithm with scoring
• Investment portfolio lifecycle management
• Real-time market insights and analytics
• Secure payment processing with crypto wallet integration
• Deal status workflow (available → locked → due diligence → active → completed)

View Credit App Documentation →

📄 Interactive Data Room (@arda/idr)

Document negotiation and management platform - Port 3001

Structured document negotiation workflow between originators and investors. Features:

• Document version control and change tracking
• AI-powered change detection and risk assessment
• Multi-party collaboration with comments and status updates
• Role-based access control (Admin/Write/Read)
• KYB (Know Your Business) verification workflow

View IDR Documentation →

Shared Packages

• @repo/ui: Shared React component library
• @repo/eslint-config: ESLint configurations (base, Next.js, React)
• @repo/typescript-config: TypeScript configurations for all apps

Technology Stack

• Frontend: React 18 + TypeScript
• Build Tool: Vite with SWC (fast compilation)
• UI Framework: shadcn/ui + Radix UI primitives
• Styling: Tailwind CSS with custom design tokens
• State Management: TanStack React Query
• Routing: React Router DOM v6
• Form Handling: React Hook Form + Zod validation
• Icons: Lucide React
• Monorepo: Turborepo v2.5.8
• Package Manager: pnpm v9.0.0

Architecture Overview

                    ┌─────────────────────┐
                    │   Platform (3002)   │
                    │  Authentication Hub │
                    └──────────┬──────────┘
                               │
                    ┌──────────┴──────────┐
                    │  Magic Link Auth    │
                    │  Company Setup      │
                    │  JWT Token Issue    │
                    └──────────┬──────────┘
                               │
              ┌────────────────┴────────────────┐
              │                                 │
    ┌─────────▼─────────┐           ┌─────────▼─────────┐
    │  Credit App (3000)│           │    IDR (3001)     │
    │  Deal Matching    │           │  Document Mgmt    │
    │  Investments      │           │  Negotiations     │
    └───────────────────┘           └───────────────────┘

Getting Started

Prerequisites

• Node.js: >=18
• pnpm: v9.0.0 (package manager)
• Backend API: Separate backend repository running (required for all apps)

Installation

# Clone the repository
git clone <repository-url>
cd arda-platform

# Install dependencies for all workspaces
pnpm install

Environment Setup

Each application requires environment variables. Copy the example files:

# Platform app
cp apps/platform/.env.example apps/platform/.env

# Credit app
cp apps/credit-app/.env.example apps/credit-app/.env

# IDR app
cp apps/idr/.env.example apps/idr/.env

Update the .env files with your configuration:

• VITE_SERVER_URL: Backend API endpoint (empty string in production for relative paths)
• VITE_CHAT_AGENT_URL: Chat agent endpoint (empty string in production for relative paths)
• VITE_CREDIT_APP_URL: Credit App URL (for Platform redirects)
• VITE_IDR_URL: IDR URL (for Platform redirects)

📖 Important: See URL Configuration Guide for detailed information about our unified URL pattern, including:

• How empty URLs enable relative paths in production
• Vite proxy configuration for development and production
• Deployment configurations for Docker, Kubernetes, and cloud platforms
• Troubleshooting mixed content errors

Development

Run All Applications

# Start all apps in parallel
pnpm dev

This will start:

• Platform on http://localhost:3002
• Credit App on http://localhost:3000
• IDR on http://localhost:3001

Run Specific Application

# Platform (authentication)
pnpm --filter=@arda/platform dev

# Credit App (investment platform)
pnpm --filter=@arda/credit-app dev

# IDR (document management)
pnpm --filter=@arda/idr dev

Alternative: Work Within App Directory

cd apps/platform
npm run dev

Building for Production

# Build all applications
pnpm build

# Build specific app
pnpm --filter=@arda/credit-app build
turbo build --filter=@arda/credit-app

Common Commands

Development

pnpm dev                              # Run all apps
pnpm --filter=@arda/platform dev      # Run specific app
turbo dev                             # Run all with Turbo

Building

pnpm build                            # Build all
turbo build --filter=@arda/credit-app # Build specific

Linting & Type Checking

pnpm lint                             # Lint all
pnpm check-types                      # Type-check all
pnpm format                           # Format all files

Turborepo Utilities

turbo build                           # Build all with caching
turbo dev --filter=@arda/*            # Run all apps only
turbo lint --filter=@repo/*           # Lint packages only

User Journey

1. Authentication (Platform)

• User enters email at http://localhost:3002/login
• Receives magic link via email
• Clicks link to verify email
• Creates company profile or accepts invitation

2. App Selection (Platform)

• User selects Credit App or IDR based on needs
• Platform issues JWT token
• User is redirected with token to selected app

3. Application Usage

• Credit App: Browse deals, lock investments, manage portfolio
• IDR: Upload documents, review changes, negotiate terms

4. Cross-App Navigation

• Users can switch between apps
• Token is valid across all applications
• No re-authentication needed

Project Structure

arda-platform/
├── apps/
│   ├── platform/       # Authentication portal (React + Vite)
│   ├── credit-app/     # Investment platform (React + Vite)
│   └── idr/            # Document management (React + Vite)
├── packages/
│   ├── ui/             # Shared components
│   ├── eslint-config/  # Shared ESLint configs
│   └── typescript-config/ # Shared TS configs
├── package.json        # Root package with workspace scripts
├── turbo.json          # Turborepo pipeline config
├── pnpm-workspace.yaml # pnpm workspace config
└── CLAUDE.md           # Developer guidance for AI assistants

Authentication Flow

1. Platform (/login) → User enters email
2. Backend → Sends magic link to email
3. Platform (/verify?token=xxx) → Validates token
4. Platform (/onboarding) → Company setup
5. Platform → Issues JWT token
6. Credit App/IDR → Receives token, validates with backend
7. App → User is authenticated and can use features

Company Types

Originator

• Creates and manages investment deals
• Uploads loan documentation to IDR
• Uses Credit App to attract investors
• Tracks active investments and payments

Investor

• Browses available deals on Credit App
• Reviews documents in IDR
• Locks deals for due diligence
• Manages investment portfolio

Development Best Practices

Adding New Features

1. Determine which app the feature belongs to
2. Add types to src/types/index.ts
3. Create API functions in src/lib/api.ts
4. Build UI components in src/components/
5. Add routes if needed
6. Use React Query for data fetching
7. Use React Hook Form + Zod for forms

Code Style

• TypeScript strict mode is disabled (be careful with types)
• Use Tailwind CSS for styling
• Follow shadcn/ui component patterns
• Use path alias @/* for imports
• Keep components small and focused

Turborepo Caching

• Build outputs are cached automatically
• Dev servers run without caching
• Use filters to run tasks on specific apps
• Remote caching available via Vercel

Docker Support

Credit App includes Docker support:

cd apps/credit-app

# Build Docker image
npm run docker:build

# Run with Docker Compose
npm run docker:up

# View logs
npm run docker:logs

# Stop containers
npm run docker:down

Git Workflow

This monorepo uses git subtrees for Credit App and IDR:

• Credit App and IDR were merged from separate repositories
• Platform was created directly in the monorepo
• Each app maintains independent git history
• Coordinate changes across apps when needed

Useful Links

Turborepo

• Turborepo Documentation
• Remote Caching
• Filtering Tasks

Technologies

• React Documentation
• Vite Documentation
• shadcn/ui Components
• Tailwind CSS
• React Query
• React Router

Troubleshooting

Port Conflicts

If ports are in use:

• Platform: Change port in apps/platform/vite.config.ts
• Credit App: Change port in apps/credit-app/vite.config.ts
• IDR: Change port in apps/idr/vite.config.ts

Installation Issues

# Clear node_modules and reinstall
rm -rf node_modules apps/*/node_modules packages/*/node_modules
pnpm install

Build Issues

# Clear Turbo cache
rm -rf .turbo apps/*/.turbo
turbo build --force

Backend Connection

All apps require the backend API to be running:

• Check VITE_API_URL in .env files
• Ensure backend is accessible
• Check CORS configuration on backend

Contributing

1. Create a feature branch
2. Make your changes
3. Run linting: pnpm lint
4. Run type checking: pnpm check-types
5. Test all affected apps
6. Submit a pull request

License

[Your License Here]

Support

For issues and questions:

• Platform App: See apps/platform/README.md
• Credit App: See apps/credit-app/README.md
• IDR: See apps/idr/README.md
• Developer Guide: See CLAUDE.md