agentic-mobile-blueprint

Agentic Mobile Blueprint (AMB)

AI helps you build it. AMB helps you launch it.

The production-ready foundation for shipping mobile and web apps. Auth, deployment, monitoring, and CI/CD — already wired together.

---

What You Get

📱 Mobile app — iOS and Android from one codebase (Expo + Tamagui)

🌐 Web app — Next.js + Tailwind CSS

⚡ Backend — Supabase: auth, database, storage, and edge functions

⏱️ Background jobs — Trigger.dev for async work

📊 Monitoring — Sentry, PostHog, and Langfuse wired in from day one

🤖 Agent-native — Built-in AI context files under .agents/skills/ so Cursor, Claude, and Copilot understand the framework out of the box

🚀 Ship from main — Merge to main runs path-filtered deploys (Vercel, Supabase, Trigger.dev, mobile) when those parts of the repo change

---

Prerequisites

• mise — dev environment manager (installs Node 22, Deno, Supabase CLI)
• Docker — for local Supabase

For mobile development (macOS):

• Xcode + Command Line Tools for iOS simulator
• Android Studio for Android emulator

---

Get Started

Option A: Click "Use this template" at the top of the repo to create your own copy with a clean git history.

Option B: Clone directly:

git clone https://github.com/ampli-group/agentic-mobile-blueprint.git my-app
cd my-app
rm -rf .git && git init

Install tools and dependencies

# 1. Install mise (if not already installed)
curl https://mise.run | sh

# 2. Restart your terminal or run:
eval "$(mise activate zsh)"  # or bash

# 3. Trust this project and install tools (Node, Deno, Supabase CLI)
mise trust
mise install

# 4. Install npm dependencies
mise run install

# 5. Start Supabase
mise run supabase

# 6. Configure environment variables
mise run configure

Running the apps

Open separate terminals:

# Terminal 1: Supabase Edge Functions
mise run backend

# Terminal 2: Web app
mise run frontend

# Terminal 3: Mobile app
mise run mobile
# › Press a │ open Android
# › Press i │ open iOS simulator
# › Press w │ open web

# Terminal 4: Background jobs (optional)
mise run trigger

Customize

After creating your project, update these files:

• mobile/app.json — change name, slug, and scheme
• mobile/build.json — update if using EAS Build
• .github/workflows/ci.yml — update badge URLs if your repo name differs
• Run mise run configure to regenerate local env files after Supabase or network changes
• Run mise run setup:prod when you are ready for production credentials and services

---

Production setup

Interactive setup wizard

Run the production setup wizard to configure services and env files:

mise run setup:prod

This interactive script guides you through Supabase, Vercel, Expo, optional Trigger.dev/Sentry, and more. Expect about 15–30 minutes. After the wizard, use dev-to-prod.md for manual first-pass deployment steps.

---

CI/CD & deployment

Merging to main deploys what changed (each workflow is path-filtered).

Quick deploy

git push origin main
# ✅ Frontend → Vercel           (if frontend/ changed)
# ✅ Supabase → DB + functions   (if supabase/ changed)
# ✅ Trigger.dev → jobs         (if trigger/ changed)
# ✅ Mobile → iOS + Android     (if mobile/ changed)

Workflow notes

• Everything deploys automatically on merge to main when matching paths change
• Services with missing GitHub Actions secrets are skipped gracefully
• No staging/preview environments by default
• Workflows are independent — one failure does not block the others
• Parallel builds where applicable; mobile can auto-submit to stores when configured

Documentation

dev-to-prod.md is the full production deployment guide (services, secrets, troubleshooting).

---

Stack

Layer	Technology	Purpose
Mobile	React Native + Expo + Tamagui	iOS and Android from one codebase
Web	Next.js + Tailwind CSS	Server-rendered web app
Backend	Supabase	Auth, Postgres database, storage, edge functions
Jobs	Trigger.dev	Background and async work
Monitoring	Sentry, PostHog, Langfuse	Errors, analytics, LLM observability
AI	OpenAI, Anthropic, Gemini	Multi-provider LLM support via Langfuse

Why this stack?

Each tool has one job. Supabase handles the entire backend. Expo gives you native mobile from one codebase. Next.js powers the web. Trigger.dev runs background work. Observability is wired in from the start so you do not retrofit it later. See spec.md for the full rationale.

---

Agent Skills

This framework is built for AI-assisted development. The AGENTS.md file gives coding agents full context on the codebase structure, conventions, and verification workflows. The .agents/skills/ directory contains pattern guides for each layer:

• Edge functions, frontend, and mobile development patterns
• Sentry, PostHog, and Langfuse integration guides
• EAS mobile deployment and Supabase email templates

Your AI coding assistant (Cursor, Claude, Copilot) can use these to produce code that follows the framework's conventions without you having to explain the architecture.

---

Project structure

├── .mise.toml       # Tasks and tool versions
├── AGENTS.md        # AI agent context
├── .agents/skills/  # AI coding pattern guides
├── frontend/        # Next.js + Tailwind CSS
├── mobile/          # React Native + Expo + Tamagui
├── supabase/        # Config, migrations, edge functions
├── trigger/         # Background jobs
├── scripts/         # Setup and configuration scripts
└── docs/            # Tutorials and guides

---

Documentation

Doc	Purpose
Available Commands	All mise commands and aliases
Environment Variables	Env files, naming conventions, and ports
dev-to-prod.md	Production deployment guide
spec.md	Architecture rationale
CONTRIBUTING.md	How to contribute
SECURITY.md	Security policy

---

Community

• Questions & ideas — GitHub Discussions
• Bug reports — GitHub Issues

---

Contributing

We welcome contributions — whether it is a bug fix, a new skill, or a documentation improvement. Check out CONTRIBUTING.md to get started, or browse issues labelled good first issue if you are looking for a place to jump in.

For security vulnerabilities, see SECURITY.md.

---

License

MIT — see LICENSE.

---

Built and maintained by Ampli Group — we ship our own production apps on this framework every day.

If this saved you setup time, a ⭐ helps others find it.