mortgagefi-helper/docs/Operations/Development.md

---
title: Development
tags: [mortgagefi, ops, development]
type: operations
status: stable
updated: 2026-06-14
---

# Development

## Repository Structure

```
mortgageFi/
├── mortgagefi-frontend/          # Next.js DApp
│   ├── app/                       # App Router pages
│   │   ├── dapp/page.tsx          # Main DApp interface
│   │   ├── dapp/position/...      # Deep-link position pages
│   │   ├── layout.tsx             # Root layout with Web3Provider
│   │   └── page.tsx               # Landing page
│   ├── components/                # React components
│   │   ├── ConnectButton.tsx
│   │   ├── Navbar.tsx
│   │   └── SettingsModal.tsx      # Notification settings
│   ├── providers/
│   │   └── Web3Provider.tsx       # Wagmi + QueryClient setup
│   ├── utils/
│   │   ├── scheduler.ts           # Schedy API client
│   │   ├── useLocalStorage.ts     # localStorage hook
│   │   ├── format.ts              # Number formatting
│   │   └── cronhost.ts            # Legacy cronhost support
│   ├── config/
│   │   └── web3.ts                # Wagmi chain config
│   ├── types/
│   │   └── notifications.ts       # TypeScript types
│   ├── ABIs/
│   │   └── mortgagefiusdccbbtcupgraded.json
│   └── submodules/
│       └── schedy/                # Go scheduler (Git submodule)
├── nftcache/                      # Go NFT ownership cache
│   ├── cmd/nftcache/main.go
│   └── internal/
│       ├── config/config.go       # YAML contract config
│       ├── fetcher/
│       │   ├── rpc.go             # RPC scanning with rate limits
│       │   └── alchemy.go         # Alchemy API fallback
│       └── store/store.go         # BadgerDB persistence
├── config/
│   └── contracts.yaml             # Contract address mappings
├── nginx/
│   └── nginx.conf                 # Reverse proxy config
├── docker-compose.yml             # Full stack orchestration
├── .env / .env.local              # Environment variables
├── ALERT_CHANGES.md              # Alert feature changelog
└── MIGRATION_NOTES.md            # Dependency upgrade notes
```

---

## Frontend Development

### Setup

```bash
cd mortgagefi-frontend
npm install
```

### Run Dev Server

```bash
npm run dev
# Opens on http://localhost:3000
```

> [!info]
> Turbopack is enabled by default for faster builds.

### Build for Production

```bash
npm run build
npm start
```

### Lint

```bash
npm run lint
```

### Environment Variables

Create `mortgagefi-frontend/.env.local`:

```bash
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your-project-id
NEXT_PUBLIC_RPC_BASE=https://base.llamarpc.com
```

> [!note]
> See `.env` in the repo root for the full variable list.

---

## Backend Development

### nftcache

```bash
cd nftcache

# Run
go run ./cmd/nftcache

# Build
go build -o nftcache ./cmd/nftcache
./nftcache

# With custom env
NFTCACHE_API_KEY=test NFTCACHE_TTL=1h go run ./cmd/nftcache
```

**Test the API:**
```bash
# After starting, test with:
curl "http://localhost:8090/nfts?network=base&nft_contract=cbbtc&user_wallet=0x..."
```

### schedy

```bash
cd mortgagefi-frontend/submodules/schedy

# Run
go run ./cmd/schedy

# Build
go build -o schedy ./cmd/schedy
./schedy -port 8080
```

**Test the API:**
```bash
# Create a task
curl -X POST http://localhost:8080/tasks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: test" \
  -d '{
    "url": "https://httpbin.org/post",
    "execute_at": "2026-12-31T23:59:59Z",
    "payload": "test"
  }'

# List tasks
curl http://localhost:8080/tasks -H "X-API-Key: test"
```

---

## Full Stack Local Development

Run all services together with Docker Compose:

```bash
# From repo root
docker compose up -d

# Watch logs
docker compose logs -f

# Restart a single service
docker compose restart frontend
docker compose restart nftcache

# Rebuild after code changes
docker compose up -d --build frontend
docker compose up -d --build nftcache
```

The nginx proxy exposes everything on `http://localhost`:
- `/` — Next.js frontend
- `/ntfy/` — ntfy web UI and API
- `/schedy/` — Schedy API
- `/nftcache/` — nftcache API

---

## Adding a New Chain/Preset

### 1. Update Frontend (`mortgagefi-frontend/app/dapp/page.tsx`)

Add chain defaults:
```typescript
const DEFAULTS = {
  [base.id]: { nft: '0x...', debt: '0x...' },
  [arbitrum.id]: { nft: '0x...', debt: '0x...' },
  [newChain.id]: { nft: '0x...', debt: '0x...' },
};
```

Add presets:
```typescript
const PRESETS = {
  [newChain.id]: [
    { key: 'PAIR-QUOTE', label: 'PAIR-QUOTE', nft: '0x...', debt: '0x...' },
  ],
};
```

### 2. Update Web3 Config (`mortgagefi-frontend/config/web3.ts`)

```typescript
import { newChain } from 'wagmi/chains';

export const config = createConfig({
  chains: [base, arbitrum, newChain],
  transports: {
    [newChain.id]: http('https://newchain.rpc.com'),
  },
});
```

### 3. Update nftcache (`config/contracts.yaml`)

```yaml
contracts:
  mypreset:
    network: newchain
    address: "0x..."
    max_token_id: "10000"
```

### 4. Add RPC to nftcache environment

```bash
NEWCHAIN_RPC_URL=https://newchain.rpc.com
```

Update `nftcache/cmd/nftcache/main.go` to read the new env var.

---

## Testing Notifications End-to-End

### 1. Configure Settings in UI

Open the DApp, click Settings (gear icon):
- **Provider:** ntfy
- **Server:** `/ntfy` (or your ntfy URL)
- **Topic:** `mortgagefi-test`
- **Email:** your email address
- **Scheduler:** Schedy
- **Schedy URL:** `/schedy`
- **Schedy API Key:** your key

### 2. Send Test Alert

Click "Send test alert" in Settings.

### 3. Verify

Check:
- ntfy web UI at `http://localhost/ntfy/` — message should appear
- Your email inbox — message should arrive within seconds (or 2 minutes for Schedy tests)

### 4. Manual Test via cURL

```bash
# Direct ntfy test
curl -X POST http://localhost/ntfy/mortgagefi-test \
  -H "Content-Type: text/plain" \
  -H "X-Email: you@example.com" \
  -d "Manual test"

# Schedy + ntfy test
curl -X POST http://localhost/schedy/tasks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "url": "http://localhost/ntfy/mortgagefi-test",
    "headers": {"Content-Type":"text/plain","X-Email":"you@example.com"},
    "payload": "Scheduled test",
    "execute_at": "'$(date -u -v+2M +%Y-%m-%dT%H:%M:%SZ)'"
  }'
```

---

## Common Issues

### 429 Rate Limit Errors

> [!warning] RPC returns "Too Many Requests" during NFT scanning.

**Solutions:**
- Use a private RPC endpoint (Infura, Alchemy, QuickNode)
- Reduce `NFTCACHE_TTL` to reduce background refresh frequency
- Enable nftcache in frontend settings to offload scanning

### Wallet Connection Fails

> [!warning] WalletConnect modal doesn't appear.

**Solutions:**
- Verify `NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID` is set
- Check that the project ID is valid at https://cloud.walletconnect.com

### Schedy Tasks Not Executing

> [!warning] Scheduled alerts never fire.

**Debugging:**
```bash
# List pending tasks
curl http://localhost/schedy/tasks -H "X-API-Key: your-key"

# Check schedy logs
docker compose logs -f schedy
```

**Common causes:**
- Schedy container clock drift (ensure NTP is enabled)
- Task deleted before execution (check auto-reschedule logic)
- ntfy URL unreachable from Schedy container

### CORS Errors

> [!warning] Browser blocks API calls to Schedy or nftcache.

**Solution:**
Ensure `CORS_ALLOW_ORIGIN` matches your frontend URL exactly, including protocol:
```bash
CORS_ALLOW_ORIGIN=https://mortgagefi.example.com
```

---

## Git Submodules

The `schedy` project is included as a Git submodule:

```bash
# Initialize on fresh clone
git submodule update --init --recursive

# Pull latest submodule changes
git submodule update --remote

# Commit submodule pin
cd mortgagefi-frontend/submodules/schedy
git checkout main
git pull
cd ../../..
git add mortgagefi-frontend/submodules/schedy
git commit -m "Update schedy submodule"
```

---

## Related

- [[Home]]
- [[Architecture]]
- [[API Reference]]
- [[Deployment]]