Technical Documentation

System Architecture

Open Mandi is built as a monolithic Next.js application using the App Router paradigm. The architecture prioritizes simplicity and transparency, suitable for an academic exchange handling low-volume trading activity.

Technology Stack

Frontend Architecture

The frontend uses the Next.js App Router with route groups to organize the application into distinct sections, each with its own layout:

• (marketing) — Landing page with promotional content
• (docs) — Documentation hub with sidebar navigation
• (exchange) — Trading application with dashboard layout
• (legal) — Terms and conditions with minimal layout

React Server Components (RSC) are used by default. Client components (marked with "use client") are limited to interactive elements such as sidebar navigation with active-state detection, order entry forms, and real-time data displays.

Backend Architecture

The backend is implemented using Next.js API routes (app/api/) and Server Actions. The architecture follows a layered pattern:

┌─────────────────────────┐
│   API Routes / Actions  │  ← HTTP handlers, input validation
├─────────────────────────┤
│    Service Layer        │  ← Business logic, orchestration
├─────────────────────────┤
│    Repository Layer     │  ← Data access, queries
├─────────────────────────┤
│    Database             │  ← Persistent storage
└─────────────────────────┘

Implementation details for the backend layers will be documented as they are built in subsequent sprints.

Database Layer

The database schema will be implemented with a relational database to ensure ACID compliance for financial transactions. Key design principles:

• Double-entry bookkeeping for all balance changes
• Atomic transactions for order matching and settlement
• Immutable audit trail for all financial operations
• Optimistic locking to prevent race conditions on balance updates

Authentication & Session Management

Authentication is handled via Firebase Auth with Google sign-in as the identity provider. Upon successful authentication, the server creates an HTTP-only __session cookie containing a Firebase session token. Server-side routes verify this cookie to identify the current user and look up their PostgreSQL record.

Deployment Architecture

Coming Soon — Deployment configuration and infrastructure details will be documented as the platform moves toward hosting.

Scalability Considerations

As an academic exchange with low transaction volumes and strict deposit limits ($5 max), the architecture is designed for correctness and transparency rather than high-throughput performance. The monolithic approach is appropriate for this scale and simplifies debugging, deployment, and educational inspection of the system.

Should volume requirements increase, the matching engine and WebSocket feeds are the primary candidates for extraction into dedicated services.