> For the complete documentation index, see [llms.txt](https://wally-3.gitbook.io/wally-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wally-3.gitbook.io/wally-docs/technical/index.md).

# Architecture

Wally is a **TypeScript monorepo** with 4 applications and 2 shared packages, deployed on **Stellar blockchain** with **Soroban** smart contracts.

***

## Monorepo Structure

```
remesas-escrow/
├── apps/
│   ├── api/              # NestJS backend (GraphQL)
│   ├── web/              # Next.js 16 frontend
│   ├── mobile/           # React Native (Expo)
│   └── wallet-ext/       # Chrome extension (Manifest V3)
├── packages/
│   ├── wallet-core/      # Stellar + Soroban + Blend + Crypto utils
│   └── wallet-sdk/       # @wally/connect SDK for dApps
└── docs/                 # Documentation (this GitBook)
```

***

## Technology Stack

### Backend (`apps/api`)

* **Framework**: [NestJS](https://nestjs.com/) 10 + GraphQL (code-first)
* **Database**: PostgreSQL ([Neon](https://neon.tech/) serverless) + [Prisma](https://www.prisma.io/) ORM
* **Authentication**: JWT + Magic Links + Google OAuth

### Web Frontend (`apps/web`)

* **Framework**: [Next.js](https://nextjs.org/) 16 (App Router)
* **Styling**: Tailwind CSS with CSS custom properties (dark/light theme)
* **State**: React Context (AuthContext, WalletContext)
* **API**: GraphQL via `gqlFetch` utility

### Mobile Application (`apps/mobile`)

* **Framework**: [Expo](https://expo.dev/) / React Native
* **Navigation**: React Navigation
* **Styling**: NativeWind (Tailwind for React Native)

### Wallet Extension (`apps/wallet-ext`)

* **Type**: Chrome extension (Manifest V3)
* **Compatibility**: Freighter-compatible API
* **SDK**: `@wally/connect` for dApp integration

### Shared Packages

**`packages/wallet-core`** — Core blockchain operations:

* `StellarClient`: Horizon operations (payments, trustlines, balances)
* `SorobanClient`: Soroban RPC (smart contracts, simulate, submit)
* `BlendClient`: Blend Capital DeFi pool interaction
* `CryptoUtils`: AES-256-GCM encryption with PBKDF2

**`packages/wallet-sdk`** — SDK for third-party dApp integration (`@wally/connect`)

### Blockchain Integration

* **Network**: Stellar (Horizon + Soroban)
* **Asset**: USDC (Circle)
* **Escrow**: TrustlessWork (non-custodial smart contracts)
* **DeFi**: Blend Capital (lending/yield pools)
* **Off-ramp**: MoneyGram SEP-24

***

## Infrastructure

| Component  | Service | Tier                  |
| ---------- | ------- | --------------------- |
| API        | Render  | Web Service           |
| Web        | Vercel  | Pro                   |
| Database   | Neon    | Serverless PostgreSQL |
| Blockchain | Stellar | Testnet / Mainnet     |
