How exactly/exa works
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