Architecture

Locale Lending's and Data Flow & Technical Architecture

The Locale Lending's data flow and API architecture involve the following steps:

Data Collection:

• Bank Account to Plaid API: Financial data is collected from bank accounts using the Plaid API.

• Plaid API to HTTPs API Gateway: This data is sent to a Next.js server acting as an HTTPs API Gateway that will transform, encrypt and report to a standard webpage.

Data Processing:

• Reclaim Protocol Integration: The financial data is converted into a JSON file, which is then processed through the Reclaim Protocol to produce a zk-proof on Arbitrum. This ensures the data's integrity and validity.

• Storage in SQLite Database: The encrypted data, is sent to the backend inside of the CVM via a JSON file, further processed, and stored in an SQLite database via an input payload

Smart Contract Interaction:

• Loan Health Monitoring: Drastic changes in loan health trigger recalculations of interest rates and limits. These calculations are performed consistently on Cartesi, using financial and smart contract data.

• Smart Contract Updates: The results from these calculations are used as parameters to call smart contract functions, updating the loan terms accordingly.

Front-End Reporting:

• Investor Dashboard: Important loan health metrics and zk-proof links are reported on the front-end in an investor dashboard.

• Compliance and Reporting: Potential compliance and reporting to the SBA are triggered by changes in the smart contracts, ensuring regulatory adherence.

Architecture

System Overview

Locale is built on a multi-layer architecture combining traditional web services with blockchain infrastructure and off-chain computation.

graph TB
    subgraph "Client Layer"
        Web[Next.js Web App]
        Wallet[Alchemy Account Kit]
    end

    subgraph "API Layer"
        API[Next.js API Routes]
        Auth[Authentication]
        RateLimit[Rate Limiting]
    end

    subgraph "Service Layer"
        Plaid[Plaid Integration]
        DSCR[DSCR Calculator]
        NFT[Credential Minting]
        Relay[Transaction Relay]
    end

    subgraph "Data Layer"
        Postgres[(PostgreSQL)]
        Supabase[(Supabase)]
        Cache[Redis Cache]
    end

    subgraph "Blockchain Layer"
        Arbitrum[Arbitrum Network]
        subgraph "Smart Contracts"
            LP[SimpleLoanPool]
            SP[StakingPool]
            PV[PoolVault]
            BC[BorrowerCredential]
            IC[InvestorCredential]
            Ver[ProofVerifier]
        end
    end

    subgraph "Off-Chain Compute"
        Cartesi[Cartesi Rollups]
        ZK[ZK Circuits]
    end

    Web --> Wallet
    Web --> API
    Wallet --> Arbitrum
    API --> Auth
    Auth --> RateLimit
    RateLimit --> Plaid
    RateLimit --> DSCR
    RateLimit --> NFT
    API --> Postgres
    API --> Supabase
    DSCR --> Cartesi
    Cartesi --> LP
    ZK --> Ver
    NFT --> BC
    NFT --> IC
    Relay --> Arbitrum

Technology Stack

Frontend

Technology	Purpose
Next.js 15	React framework with App Router
React 19	UI components
TypeScript 5	Type safety
Tailwind CSS	Styling
shadcn/ui	Component library
TanStack Query	Data fetching & caching
wagmi + viem	Web3 hooks & client

Backend

Technology	Purpose
Next.js API Routes	REST API endpoints
Prisma	ORM for PostgreSQL
NextAuth.js	Session management
Alchemy Account Kit	Wallet abstraction

Blockchain

Technology	Purpose
Solidity 0.8.22	Smart contract language
Foundry	Development & testing
OpenZeppelin	Contract standards
Arbitrum	L2 network

Off-Chain

Technology	Purpose
Cartesi	Verifiable computation
Circom	ZK circuit language
snarkjs	Groth16 proof generation
Plaid	Bank account integration

Component Details

1. Web Application

The frontend is a Next.js application using the App Router pattern:

src/app/
├── (auth)/           # Authentication pages
├── admin/            # Admin dashboard
├── approver/         # Loan approval interface
├── borrower/         # Borrower portal
├── explore/          # Public pool discovery
└── api/              # API routes

Key Features:

• Server-side rendering for SEO

• Role-based page access

• Real-time portfolio updates

• Responsive design

2. API Layer

33+ REST endpoints organized by domain:

Domain	Endpoints	Auth Required
/api/pools/*	Pool CRUD, deployment	Mixed
/api/portfolio/*	User stakes, transactions	Yes
/api/loan/*	DSCR status, applications	Yes
/api/admin/*	Dashboard, management	Admin
/api/plaid/*	Webhooks	Webhook signature

3. Smart Contracts

Six core contracts deployed on Arbitrum:

graph LR
    subgraph "Lending"
        LP[SimpleLoanPool]
    end

    subgraph "Investing"
        SP[StakingPool]
        PV[PoolVault]
    end

    subgraph "Identity"
        BC[BorrowerCredential]
        IC[InvestorCredential]
    end

    subgraph "Verification"
        Ver[ProofVerifier]
    end

    LP --> Ver
    LP --> BC
    SP --> IC
    PV --> SP

Contract Patterns:

• UUPS Upgradeable Proxy

• Role-Based Access Control

• Reentrancy Guards

• Pausable

4. Cartesi Integration

Off-chain computation via Cartesi rollups:

sequenceDiagram
    participant API as Backend API
    participant IB as InputBox
    participant CD as Cartesi DApp
    participant LP as SimpleLoanPool

    API->>IB: Submit DSCR Input
    IB->>CD: Process Request
    CD->>CD: Calculate DSCR
    CD->>CD: Determine Interest Rate
    CD-->>LP: Emit Notice
    LP->>LP: Update Loan Rate

Cartesi DApp Handlers:

• register_borrower - Initialize borrower record

• create_loan - Create loan entry

• sync_transactions - Process bank transactions

• calculate_dscr - Compute debt service ratio

• update_rate - Propose interest rate change

5. ZK Circuits

Circom circuits for privacy-preserving proofs:

Circuit	Purpose
kyc_verification.circom	Prove KYC without revealing data
dscr_threshold.circom	Prove DSCR meets threshold
plaid_commitment.circom	Commit to bank data

Proof Flow:

1. Generate witness from private inputs

2. Create Groth16 proof

3. Submit proof to verifier contract

4. Contract validates without seeing inputs

Data Flow

Loan Application Flow

graph TB
    A[Borrower] -->|1. Connect Wallet| B[Web App]
    B -->|2. Start KYC| C[Plaid Identity]
    C -->|3. Webhook| D[API]
    D -->|4. Mint| E[BorrowerCredential]
    A -->|5. Apply| B
    B -->|6. Connect Bank| F[Plaid Link]
    F -->|7. Transactions| D
    D -->|8. Submit| G[Cartesi]
    G -->|9. DSCR + Rate| D
    D -->|10. Create Loan| H[SimpleLoanPool]

Staking Flow

graph TB
    A[Investor] -->|1. Connect Wallet| B[Web App]
    B -->|2. Select Pool| C[Pool Details]
    C -->|3. Enter Amount| B
    B -->|4. Approve USDC| D[Token Contract]
    B -->|5. Stake| E[StakingPool]
    E -->|6. Issue Shares| A
    E -->|7. Record| F[(Database)]

Database Schema

Key tables in PostgreSQL:

erDiagram
    Account ||--o{ LoanApplication : has
    Account ||--o{ InvestorStake : has
    LoanPool ||--o{ InvestorStake : contains
    LoanPool ||--o{ PoolLoan : funds
    LoanApplication ||--|| PoolLoan : becomes
    LoanApplication ||--o{ Transaction : monitors
    LoanApplication ||--o{ DSCRCalculationLog : tracks

    Account {
        string id PK
        string address UK
        string role
        string privyUserId
    }

    LoanPool {
        string id PK
        string name
        string slug UK
        string status
        decimal poolSize
        decimal minimumStake
    }

    LoanApplication {
        string id PK
        string accountId FK
        decimal amount
        string status
        decimal interestRate
    }

    InvestorStake {
        string id PK
        string accountId FK
        string poolId FK
        decimal amount
        decimal shares
    }

Security Architecture

Authentication Flow

sequenceDiagram
    participant U as User
    participant W as Web App
    participant A as Alchemy
    participant S as Session

    U->>W: Connect Wallet
    W->>A: Initialize Account Kit
    A->>U: Auth Challenge
    U->>A: Sign/Verify
    A->>W: Session Token
    W->>S: Create Session
    S->>W: Session Cookie

Authorization Layers

Layer	Mechanism
API Routes	NextAuth session + role check
Smart Contracts	AccessControl roles
Webhooks	Signature verification
Cron Jobs	Secret token validation

Deployment Architecture

Production Environment

graph TB
    subgraph "Vercel"
        Web[Next.js App]
        API[API Routes]
        Cron[Cron Jobs]
    end

    subgraph "Database"
        PG[(Vercel Postgres)]
        SB[(Supabase)]
    end

    subgraph "Blockchain"
        Arb[Arbitrum One]
        Cart[Cartesi Network]
    end

    subgraph "External"
        Plaid[Plaid API]
        Alchemy[Alchemy RPC]
    end

    Web --> API
    API --> PG
    API --> SB
    API --> Plaid
    Web --> Alchemy
    Alchemy --> Arb
    API --> Cart
    Cron --> API

Environment Configuration

Variable	Purpose
DATABASE_URL	PostgreSQL connection
NEXT_PUBLIC_ALCHEMY_API_KEY	Blockchain RPC
PLAID_CLIENT_ID	Bank integration
CARTESI_GRAPHQL_URL	Off-chain compute
POOL_ADMIN_PRIVATE_KEY	Contract deployment

Performance Considerations

Caching Strategy

• API Responses - Redis/Vercel KV for frequent queries

• Blockchain Data - TanStack Query with stale-while-revalidate

• Static Assets - Vercel CDN

Rate Limiting

Endpoint Type	Limit
Public APIs	100 req/min
Authenticated	200 req/min
Webhooks	1000 req/min
Admin	50 req/min