loop

Moldi Monorepo

Unified repository for Moldi’s FastAPI backend and Expo mobile application.

Project Structure

loop/
├── apps/
│   ├── api/          # FastAPI backend (Python 3.11)
│   └── mobile/       # Expo + React Native mobile app  <-- the ONLY mobile project
├── packages/
│   └── shared/       # Shared types and utilities (empty for now)
├── pnpm-workspace.yaml
├── package.json      # Root workspace scripts (no app entry point, by design)
├── docker-compose.yml
├── .env
└── README.md

All mobile builds run from apps/mobile. The repository root has no app.json, eas.json, metro.config.js or native android//ios/ directories — it is a workspace container, not an application. A stale second Expo project used to live here; running eas build from the root now fails immediately rather than producing a build with the wrong version code and no Firebase or AppsFlyer wiring.

Prerequisites

Node.js: 18.x or higher
pnpm: 8.x or higher (npm install -g pnpm)
Python: 3.11
Docker: For PostgreSQL and Redis

Getting Started

1. Install Dependencies

# Install Node.js dependencies (all workspaces)
pnpm install

# Install Python dependencies for backend
pnpm install:api

2. Set Up Environment

# Copy environment template
cp .env.example .env

# Edit .env with your configuration
# At minimum, update these values:
# - JWT_SECRET (generate a secure random string)
# - CLOUDINARY_* (if using uploads)
# - EXPO_PUBLIC_API_BASE_URL (mobile's backend URL)

# Optional: host-only overrides (recommended for local CLI commands)
# Create a .env.local with values that should override .env on your machine.
# Example (use localhost when running Alembic locally):
# DATABASE_URL=postgresql+psycopg2://loop:loop@localhost:5432/loop
# REDIS_URL=redis://localhost:6379

3. Start Infrastructure

# Start PostgreSQL and Redis
pnpm docker:up

# Run database migrations
pnpm db:migrate

4. Start Development Servers

# Start both backend and mobile in parallel
pnpm dev

# Or start individually:
pnpm dev:api      # Backend only (http://localhost:8000)
pnpm dev:mobile   # Mobile only (Expo DevTools)

Available Scripts

Root Scripts

pnpm dev - Start both backend and mobile in parallel
pnpm dev:api - Start backend only
pnpm dev:mobile - Start mobile only
pnpm install:api - Install Python dependencies
pnpm docker:up - Start Docker services (PostgreSQL + Redis)
pnpm docker:down - Stop Docker services
pnpm db:migrate - Run Alembic migrations
pnpm db:revision - Create new migration (pass -m "message")
pnpm ios - Run iOS app via @loop/mobile workspace
pnpm android - Run Android app via @loop/mobile workspace

Backend Scripts (from apps/api)

cd apps/api
source .venv/bin/activate

# Development
uvicorn app.main:app --reload

# Database
alembic upgrade head
alembic revision --autogenerate -m "migration name"
alembic downgrade -1

# Testing
pytest

Mobile Scripts (from apps/mobile)

cd apps/mobile

# Development
pnpm start       # Start Expo DevTools
pnpm android     # Open on Android device
pnpm ios         # Open on iOS device

# Utilities
pnpm seed:messages  # Seed test messages
pnpm triage:android-launch  # Collect launch/crash diagnostics from adb
pnpm triage:ios-launch  # Collect launch/crash diagnostics from xcrun simctl

Architecture

Backend (apps/api)

Framework: FastAPI 0.115.6
Database: PostgreSQL 16 (via SQLAlchemy + Alembic)
Cache: Redis 7
Authentication: JWT tokens with Argon2 hashing
Storage: Cloudinary (images)
Monitoring: Sentry
Payments: RevenueCat webhooks

Key Features:

39 database migrations
WebSocket support for real-time messaging
Rate limiting (Redis-backed)
Push notifications (Expo)
Image upload with Cloudinary

Mobile (apps/mobile)

Framework: Expo SDK 54 + React Native 0.81
Routing: Expo Router v6 (file-based)
UI: React 19.1.0
Native Modules: Location, ImagePicker, SecureStore, Notifications
Payments: RevenueCat React Native SDK
State: Async Storage + React hooks

Key Features:

File-based routing with Expo Router
Google OAuth integration
Push notifications
In-app purchases (RevenueCat)
Image uploads to backend

Monorepo Configuration

pnpm Workspaces

Defined in pnpm-workspace.yaml:

packages:
  - 'apps/*'
  - 'packages/*'

Dependencies are hoisted to root node_modules/ for efficiency.

Metro Configuration

Mobile app uses metro.config.js to resolve dependencies from monorepo root:

Watches entire monorepo: watchFolders: [monorepoRoot]
Resolves from multiple node_modules/ paths
Disables hierarchical lookup for consistency

Docker Compose

Services:

db: PostgreSQL 16 (port 5432)
redis: Redis 7 (port 6379)
api: FastAPI backend (port 8000) - optional, usually run directly

Environment Variables

The backend reads .env and then .env.local (local overrides win). Use .env.local for host-only settings (e.g., localhost DB/Redis) while keeping Docker defaults in .env.

Backend Variables

See .env.example for full list. Key variables:

DATABASE_URL - PostgreSQL connection string
JWT_SECRET - Secret for JWT token signing
GOOGLE_OAUTH_* - Google Sign-In server-side verification config
CLOUDINARY_* - Image upload credentials
SENTRY_DSN - Error monitoring
REVENUECAT_WEBHOOK_SECRET - Payment webhooks

Mobile Variables

EXPO_PUBLIC_API_BASE_URL - Backend API URL (e.g., http://localhost:8000/api)
EXPO_PUBLIC_GOOGLE_*_CLIENT_ID - OAuth credentials

Note: Expo only exposes variables with EXPO_PUBLIC_ prefix to the app.

Troubleshooting

Backend won’t start

Verify Python 3.11 is installed: python3.11 --version
Check virtual environment: cd apps/api && source .venv/bin/activate
Verify PostgreSQL is running: docker ps (should show postgres:16)
Check .env has DATABASE_URL set

Mobile bundler errors

Clear Metro cache: cd apps/mobile && pnpm start --clear
Check metro.config.js exists with monorepo paths
Verify node_modules/ exists at root: ls node_modules/expo

Mobile can’t connect to backend

For physical devices: Replace localhost with your computer’s local IP in .env:
```
EXPO_PUBLIC_API_BASE_URL=http://192.168.x.x:8000/api
```
Ensure backend is bound to 0.0.0.0 (not 127.0.0.1)
Check CORS settings in backend config

Android Google Sign-In returns `DEVELOPER_ERROR` (Play closed testing)

Run triage helper:

cd apps/mobile && pnpm triage:google-signin

In Play Console (Setup -> App integrity), copy SHA-1/SHA-256 from App signing certificate
In Google Cloud Console (APIs & Services -> Credentials), update Android OAuth client for package com.moldi.app with those fingerprints
Ensure Android/Web/iOS OAuth clients are in the same Google Cloud project
Wait 5-10 minutes, upload a new AAB, and retest from Play closed track install

Database migration errors

Check database is running: docker ps
Verify connection: psql postgresql://loop:loop@localhost:5432/loop
Review migration files: apps/api/alembic/versions/

Reset database (WARNING: deletes data):

pnpm docker:down
docker volume rm loop_pgdata
pnpm docker:up
pnpm db:migrate

Migration from Separate Repos

This monorepo consolidates:

Backend: /Users/ardaerdogan/Documents/GitHub/loop-backend/backend/ → apps/api/
Mobile: /Users/ardaerdogan/loop-mobile/ → apps/mobile/

Git history was reset for simplicity. Old repositories remain at original paths for reference.

Development Workflow

Single Command Development

# Start everything
pnpm dev

This runs:

Backend on http://localhost:8000
Mobile Expo server with QR code

Individual Service Development

# Backend only
pnpm dev:api

# Mobile only
pnpm dev:mobile

Testing Mobile on Physical Device

Start backend: pnpm dev:api
Get your computer’s local IP: ifconfig | grep "inet "

Update .env:

EXPO_PUBLIC_API_BASE_URL=http://192.168.x.x:8000/api

Start mobile: pnpm dev:mobile
Scan QR code with Expo Go app

Contributing

Create a feature branch
Make your changes
Test both backend and mobile
Submit a pull request