App Factory Architecture Guide

Overview

App Factory Forge is designed to make it dead simple to create and deploy full-stack applications. This guide explains the architectural decisions and available options.

Design Philosophy

Keep It Simple

The core philosophy is simplicity over complexity:

• ✅ One service is better than many - Fewer moving parts, less to manage
• ✅ Defaults matter - Smart defaults get you 90% of the way
• ✅ Progressive complexity - Start simple, add complexity only when needed
• ✅ Developer experience first - If it's hard to use, it's wrong

Flexibility When Needed

While we default to simplicity, power users can:

• 🔧 Choose different infrastructure providers
• 🔧 Customize authentication strategies
• 🔧 Deploy to multiple cloud providers
• 🔧 Bring their own infrastructure

Infrastructure Providers

Default: Supabase (Recommended)

Why Supabase?

Supabase is the default and recommended provider for App Factory applications because it provides everything you need in one service:

┌──────────────────────────────────────────────┐
│         SUPABASE (All-in-One)                │
│  ┌────────────┬─────────┬──────────────┐    │
│  │ PostgreSQL │  Auth   │   Storage    │    │
│  │  Database  │ (OAuth) │  (S3-like)   │    │
│  └────────────┴─────────┴──────────────┘    │
│                                              │
│  ✅ ONE service, ONE bill                    │
│  ✅ Built-in auth (no NextAuth needed)       │
│  ✅ Instant database branching               │
│  ✅ $0-25/month total cost                   │
└──────────────────────────────────────────────┘

Cost Comparison:

Approach	Monthly Cost	Services to Manage
Supabase	$0-25	1
AWS RDS + VPC + Clerk	$74+	3+
Neon + Clerk + S3	$44+	3+

Features Included:

• PostgreSQL database with automatic backups
• Authentication (OAuth, email, magic links)
• S3-compatible storage
• Real-time subscriptions
• Edge functions
• Database branching for development
• Auto-generated REST and GraphQL APIs
• Admin dashboard

When to Choose Supabase:

• ✅ Building an MVP
• ✅ Want the fastest time-to-market
• ✅ Need built-in authentication
• ✅ Want to minimize infrastructure management
• ✅ Budget-conscious projects
• ✅ Real-time features needed

Alternative: Neon (Database-Only)

Why Neon?

Neon is a serverless PostgreSQL provider with excellent developer experience:

┌────────────────────────┐
│   Neon PostgreSQL      │
│  - Scale-to-zero       │
│  - Instant branching   │
│  - $0-19/month         │
└──────────┬─────────────┘
           │
           ▼
    Need to add separately:
    - Auth (Clerk/NextAuth)
    - Storage (S3/R2)
    - Functions (Vercel/AWS)

When to Choose Neon:

• ✅ You only need a database
• ✅ You already have auth/storage solutions
• ✅ You want pure PostgreSQL without extras
• ✅ You need advanced database branching for CI/CD

Advanced: AWS/GCP (Full Control)

Why AWS/GCP?

For enterprises or teams that need full infrastructure control:

┌─────────────────────────────────────────┐
│         AWS Infrastructure              │
│  ┌────────┬────────┬──────────┐        │
│  │  RDS   │   S3   │  Lambda  │        │
│  │  VPC   │   CDN  │ Gateway  │        │
│  └────────┴────────┴──────────┘        │
│                                         │
│  ⚠️  Multiple services to manage        │
│  ⚠️  Higher complexity                  │
│  ⚠️  $50-200/month                      │
│  ✅ Full control and customization      │
└─────────────────────────────────────────┘

When to Choose AWS/GCP:

• ✅ Enterprise compliance requirements
• ✅ Need specific AWS/GCP services
• ✅ Team has cloud infrastructure expertise
• ✅ Custom networking requirements
• ✅ Advanced security and compliance needs

Authentication Strategies

Default: Supabase Auth (Recommended)

When using Supabase, authentication is built-in:

// Sign in with Google
const { data, error } = await supabase.auth.signInWithOAuth({
  provider: 'google',
});

// Get current user
const { data: { user } } = await supabase.auth.getUser();

Features:

• OAuth providers (Google, GitHub, Twitter, etc.)
• Email/password authentication
• Magic link (passwordless) login
• Phone authentication with SMS
• Multi-factor authentication (MFA)
• Row Level Security integration

Alternative: NextAuth.js

For AWS/Neon setups without built-in auth:

// Configure NextAuth with providers
export const authOptions = {
  providers: [
    GoogleProvider({ ... }),
    GitHubProvider({ ... }),
  ],
};

Advanced: Clerk

For centralized auth across multiple apps:

auth.yourdomain.com → Central auth service
  ├─ app1.yourdomain.com
  ├─ app2.yourdomain.com  
  └─ app3.yourdomain.com

Decision Matrix

Use this matrix to choose your infrastructure:

Your Situation	Recommended Provider	Why
Building MVP	Supabase	Fastest to market, lowest cost
Startup with <100K users	Supabase	Best value, scales well
Need only database	Neon	Clean PostgreSQL experience
Enterprise compliance	AWS/GCP	Full control and security
Budget-conscious	Supabase	Free tier → $25/month
Real-time apps	Supabase	Built-in real-time subscriptions
Existing AWS setup	AWS	Leverage existing infrastructure
Team knows GCP	GCP	Use familiar tooling

Architecture Patterns

Pattern 1: Simple (Supabase)

Best for: MVPs, startups, indie hackers

┌──────────────┐
│   Supabase   │ ← Everything in one place
└──────┬───────┘
       │
   ┌───┴────┐
   │        │
┌──▼──┐  ┌─▼────┐
│ Web │  │Mobile│
└─────┘  └──────┘

Setup time: 5-10 minutes
Monthly cost: $0-25
Services to manage: 1

Pattern 2: Database + Custom Auth (Neon)

Best for: Custom requirements, existing auth

┌──────────┐  ┌──────────┐
│   Neon   │  │  Clerk/  │
│    DB    │  │NextAuth  │
└────┬─────┘  └─────┬────┘
     │              │
     └──────┬───────┘
            │
        ┌───┴────┐
        │        │
    ┌───▼──┐  ┌─▼────┐
    │ Web  │  │Mobile│
    └──────┘  └──────┘

Setup time: 15-30 minutes
Monthly cost: $19-44
Services to manage: 2-3

Pattern 3: Full Stack (AWS/GCP)

Best for: Enterprises, compliance needs

┌──────────────────────────────┐
│     AWS Infrastructure       │
│  ┌────┬─────┬──────┬──────┐ │
│  │RDS │ S3  │Lambda│  CDN │ │
│  └────┴─────┴──────┴──────┘ │
└───────────────┬──────────────┘
                │
        ┌───────┴────────┐
        │                │
    ┌───▼──┐      ┌─────▼─────┐
    │ Web  │      │  Mobile   │
    └──────┘      └───────────┘

Setup time: 30-60 minutes
Monthly cost: $50-200+
Services to manage: 5-10

Migration Paths

From AWS to Supabase

Why migrate?

• Reduce costs by 60-70%
• Simplify infrastructure
• Get built-in features (auth, storage, real-time)

Steps:

1. Export data from RDS
2. Create Supabase project via Forge CLI
3. Import data using SQL
4. Update connection strings in Doppler
5. Migrate to Supabase Auth (optional)
6. Test thoroughly
7. Destroy AWS resources

Estimated time: 2-4 hours

From Supabase to AWS

Why migrate?

• Enterprise compliance requirements
• Need specific AWS services
• Custom networking needs

Steps:

1. Export Supabase data
2. Provision AWS infrastructure via Pulumi
3. Import data to RDS
4. Set up separate auth service (Clerk/NextAuth)
5. Set up S3 for storage
6. Update all app configurations
7. Test thoroughly

Estimated time: 4-8 hours

Environment Management

All infrastructure is managed through Pulumi + Doppler:

┌─────────────┐    ┌──────────────┐    ┌─────────────┐
│   Pulumi    │───▶│   Doppler    │───▶│  Your Apps  │
│ (Provision) │    │   (Secrets)  │    │  (Consume)  │
└─────────────┘    └──────────────┘    └─────────────┘

Benefits:

• Infrastructure as code
• Automatic secret syncing
• Environment-specific configs
• Version control for infrastructure

Template Catalog Metadata

The configuration lives in ops/apps.yaml. Each app entry doubles as a template definition that powers the dashboard gallery and CLI scaffolding. The metadata block now exposes structured fields so downstream services can render consistent cards:

• persona — primary customer or operator profile the template targets.
• category — high-level grouping used for filtering (e.g. Productivity, Developer Tools).
• summary — short marketing blurb rendered in galleries and tooltips.
• tags — keyword array for search and faceted navigation; must contain at least one value.
• heroImage — relative asset path or URL for the template preview image.
• maintainer / lastUpdated — optional stewardship details retained for ops handoffs.

These fields are validated via @app-factory/config's template parser and surfaced through the dashboard API at GET /api/templates. The API returns a read-only JSON array sourced from the bundled apps.yaml, so any new template metadata must be committed to the configuration file to reach production.

Cost Optimization

Tips for Keeping Costs Low

1. Start with Supabase free tier

   • 500MB database, 50K MAU
   • Upgrade to Pro ($25) only when needed

2. Use Neon for database-only needs

   • Free tier includes 500MB
   • Scale-to-zero saves compute costs

3. Avoid AWS for MVP

   • Minimum ~$30/month even without traffic
   • VPC and networking costs add up quickly

4. Clean up unused resources

   • Regular audit of Pulumi stacks
   • Destroy development environments when not in use

Cost Monitoring

# List all Pulumi stacks
pulumi stack ls

# Check stack costs (if configured)
pulumi stack output --show-costs

# Destroy unused stacks
pulumi destroy

Best Practices

DO ✅

• Start with Supabase for new projects
• Use Doppler for all secrets and environment variables
• Version control everything (except secrets)
• Test in development before production
• Monitor costs regularly
• Clean up unused resources

DON'T ❌

• Don't overcomplicate infrastructure for MVP
• Don't commit secrets to git
• Don't use AWS unless you need it
• Don't skip backups (Supabase does this automatically)
• Don't mix providers unnecessarily
• Don't ignore cost alerts

Getting Help

Documentation

• Supabase Docs: https://supabase.com/docs
• Neon Docs: https://neon.tech/docs
• Pulumi Docs: https://www.pulumi.com/docs
• Forge CLI: forge help

Support

• File an issue: GitHub Issues
• Community: Discord/Slack
• Email: support@app-factory.com

Summary

The Simple Path (Recommended)

1. Use Supabase as your default provider
2. Leverage Pulumi for infrastructure as code
3. Store secrets in Doppler
4. Start free, upgrade when needed
5. Scale simply without complexity

When to Deviate

Only use more complex setups when you have specific requirements:

• Enterprise compliance needs → AWS/GCP
• Database-only needs → Neon
• Existing infrastructure → Keep what works

Remember: The best architecture is the one that ships fast and costs less. 🚀