# exactly/exa architecture

> Architecture diagram of the GitHub repository exactly/exa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/exactly/exa
- Repository: https://github.com/exactly/exa

## Overview

##### Project Type and Purpose
- This is a full-stack monorepo that contains:
– @exactly/mobile: a React Native (Expo) application using expo-router and Tamagui for UI, which runs on iOS and Android.
– @exactly/server: a TypeScript Node.js API server using Drizzle ORM for database access, serving REST endpoints for authentication, KYC, activity tracking, card management, etc.
– @exactly/plugin (contracts): a Foundry-based Solidity smart-contract library and deployment scripts for on-chain logic.
– common: shared constants and utility functions consumed by both mobile and server.
– docs: an Astro-based documentation website.

##### File Structure
- Top‐level packages:
– common/
– contracts/
– server/
– src/  (mobile app)
– docs/
- The mobile app (“src”) uses an “app/” directory with _layout.tsx files—this is Expo Router’s file-based routing.
- The server has server/api (endpoints), server/database (Drizzle ORM schema + configuration), server/hooks (webhook handlers), server/utils, and a testing suite under server/test.
- The contracts package contains Foundry config, Solidity source under contracts/src, scripts under contracts/script, and deployment fixtures.
- Shared code in “common” is imported by both mobile and server packages via a local package dependency.
- Deployment and CI/CD are managed via GitHub workflows (.github/workflows) and Dockerfile/app.yaml.

##### README for Additional Insights
- Confirms that the monorepo is managed with pnpm workspaces.
- Mobile runs via pnpm ios / pnpm android (Expo).
- The server and contracts packages are referenced in the README.

##### Main Components and Their Relationships
A. Mobile App (React Native/Expo)
– UI layers (expo-router pages, Tamagui components)
– Network layer (fetch or axios wrapped in queryClient/use hooks)
– On-chain client (wagmi + publicClient)
– Push notifications (OneSignal SDK)
– Authentication flows (passkeys via server/api/passkey)
B. API Server (Node.js/TypeScript)
– HTTP endpoints (server/api/*.ts)
– Business logic & hooks (server/hooks/* )
– Data access (Drizzle ORM connected to PostgreSQL or similar)
– Auth middleware, session management
– External integrations (Persona, Panda, Cryptomate, Alchemy, Sentry, Segment)
C. Smart Contracts (Foundry)
– Solidity contracts deployed on Ethereum
– Deployment scripts
– Remappings and on-chain gas snapshots
D. Shared Library (common)
– Domain constants
– Utility functions (shortenHex, deriveAddress, etc.)
E. Database
F. Blockchain Network
– Ethereum (via Alchemy / publicClient)
G. External Services
– OneSignal, Persona, Panda, Cryptomate, Sentry, Segment
H. Documentation Site (Astro)
– docs/ rendered to static site

##### Architectural Patterns and Design Principles
- Monorepo with well‐scoped packages
- File‐based routing in mobile (expo-router)
- MVC-ish layering: API routes → business/hooks → data layer (Drizzle)
- Separation of concerns: UI vs. network vs. on-chain vs. data
- Shared code for consistency across mobile and server
- Event-driven hooks for blockchain events forwarded to server

– Client Layer: Mobile App
– Server Layer: API Server + Shared Library
– Data Layer: Database + Blockchain
– Integration Layer: External Services
– Mobile → Server: HTTP calls (auth, card, activity, etc.)
– Mobile → Blockchain: on-chain transactions & queries
– Server → Blockchain: read events via Alchemy, run scripts
– Server → Database: read/write via Drizzle
– Server → External Services: OneSignal, KYC provider callbacks

##### Final Checklist
– All main components are present
– Architectural patterns (file-based routing, ORM layering, monorepo packages) are visible
– Technologies and frameworks are annotated

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer"
        Mobile["Mobile App (React Native/Expo)"]:::internal
        click Mobile "https://github.com/exactly/exa/tree/main/src/"
        subgraph "UI Layer"
            UIpages["expo-router pages"]:::internal
            click UIpages "https://github.com/exactly/exa/tree/main/src/app/"
            UILayout["Layout (_layout.tsx)"]:::internal
            click UILayout "https://github.com/exactly/exa/blob/main/src/app/_layout.tsx"
        end
        Components["Tamagui UI Components"]:::internal
        click Components "https://github.com/exactly/exa/tree/main/src/components/"
        Network["Network Layer (React Query)"]:::internal
        click Network "https://github.com/exactly/exa/blob/main/src/utils/queryClient.ts"
        OnChainClient["On-chain Client (wagmi + publicClient)"]:::internal
        click OnChainClient "https://github.com/exactly/exa/blob/main/src/utils/wagmi.ts"
        click OnChainClient "https://github.com/exactly/exa/blob/main/src/utils/publicClient.ts"
        PushNotif["Push Notifications (OneSignal SDK)"]:::external
        click PushNotif "https://github.com/exactly/exa/blob/main/src/utils/onesignal.ts"
        click PushNotif "https://github.com/exactly/exa/blob/main/public/OneSignalSDKWorker.js"
        AuthFlows["Authentication Flows (passkeys)"]:::internal
        click AuthFlows "https://github.com/exactly/exa/blob/main/src/app/onboarding/(passkeys)/passkeys.tsx"
    end

    subgraph "Server Layer"
        Server["API Server (Node.js/TypeScript)"]:::internal
        click Server "https://github.com/exactly/exa/tree/main/server/"
        Endpoints["HTTP Endpoints"]:::internal
        click Endpoints "https://github.com/exactly/exa/tree/main/server/api/"
        Hooks["Business Logic & Hooks"]:::internal
        click Hooks "https://github.com/exactly/exa/tree/main/server/hooks/"
        Drizzle["Drizzle ORM (schema + config)"]:::internal
        click Drizzle "https://github.com/exactly/exa/blob/main/server/database/schema.ts"
        click Drizzle "https://github.com/exactly/exa/blob/main/server/database/index.ts"
        click Drizzle "https://github.com/exactly/exa/blob/main/server/drizzle.config.ts"
        Middleware["Auth Middleware & Session"]:::internal
        click Middleware "https://github.com/exactly/exa/blob/main/server/middleware/auth.ts"
        Utils["Server Utilities & Integrations"]:::internal
        click Utils "https://github.com/exactly/exa/tree/main/server/utils/"
        Tests["Test Suite"]:::internal
        click Tests "https://github.com/exactly/exa/tree/main/server/test/"
    end

    subgraph "Smart Contracts"
        Contracts["Foundry Smart Contracts"]:::internal
        click Contracts "https://github.com/exactly/exa/tree/main/contracts/"
        Solidity["Solidity Source"]:::internal
        click Solidity "https://github.com/exactly/exa/tree/main/contracts/src/"
        Scripts["Deployment Scripts & Broadcast"]:::internal
        click Scripts "https://github.com/exactly/exa/tree/main/contracts/script/"
        click Scripts "https://github.com/exactly/exa/tree/main/contracts/broadcast/"
        Config["Foundry Configuration"]:::internal
        click Config "https://github.com/exactly/exa/blob/main/contracts/foundry.toml"
        click Config "https://github.com/exactly/exa/blob/main/contracts/remappings.txt"
        Snapshots["Gas Snapshots"]:::internal
        click Snapshots "https://github.com/exactly/exa/tree/main/contracts/.gas-snapshot/"
    end

    subgraph "Shared Library"
        Common["common (Shared Constants & Utils)"]:::internal
        click Common "https://github.com/exactly/exa/tree/main/common/"
    end

    subgraph "Data Layer"
        DB["PostgreSQL\n(Drizzle ORM)"]:::data
        Blockchain["Ethereum Network\n(Alchemy RPC)"]:::data
    end

    subgraph "Integration Layer"
        OneSignalSrv["OneSignal"]:::external
        PersonaSrv["Persona"]:::external
        PandaSrv["Panda"]:::external
        CryptomateSrv["Cryptomate"]:::external
        SentrySrv["Sentry"]:::external
        SegmentSrv["Segment"]:::external
    end

    docs["Documentation Site (Astro)"]:::internal
    click docs "https://github.com/exactly/exa/tree/main/docs/"

    CI["CI/CD Workflows"]:::internal
    click CI "https://github.com/exactly/exa/tree/main/.github/workflows/"

    Docker["Docker & Deployment Configs"]:::internal
    click Docker "https://github.com/exactly/exa/tree/main/Dockerfile"
    click Docker "https://github.com/exactly/exa/blob/main/.do/app.yaml"

    %% Data Flows
    Mobile -->|HTTPS/JSON| Endpoints
    Network -->|using React Query| Endpoints
    UIpages -->|renders| Mobile
    OnChainClient -->|RPC via Alchemy| Blockchain
    Server -->|SQL via Drizzle| DB
    Server -->|RPC via Alchemy| Blockchain
    Server -->|HTTP calls| OneSignalSrv
    Server -->|API calls| PersonaSrv
    Server -->|API calls| PandaSrv
    Server -->|API calls| CryptomateSrv
    Server -->|SDK| SentrySrv
    Server -->|SDK| SegmentSrv
    Mobile -->|Push SDK| PushNotif
    Mobile -->|BrowserPasskeys| AuthFlows
    AuthFlows -->|calls| Endpoints

    Common -->|shared code| Mobile
    Common -->|shared code| Server

    docs -->|published by| CI
    CI -->|deploys| docs

    %% Styling
    classDef internal fill:#D0E1FF,stroke:#0366d6
    classDef data fill:#DFFFD0,stroke:#0f0
    classDef external fill:#FFE4B5,stroke:#FFA500
```
