Developer Lifecycle

This guide walks through the real-world workflows you'll use daily. It follows a feature from inception through development, testing, deployment, and cleanup.

The Big Picture

Here's the typical development cycle:

ds setup          → One-time environment setup
    ↓
ds local run      → Daily local development
    ↓
ds deploy up      → Deploy to personal cloud stage for testing
    ↓
ds deploy down    → Clean up when finished

Everything in between is managed by the ds CLI — database migrations, secret management, code generation, and maintenance.

Scenario 1: Starting a New Feature

You've been assigned a feature. Here's the complete workflow.

1. Create a Feature Branch

git checkout -b feature/user-notifications

Your local stage remains phil-local — switching branches does not change your local environment. The same Neon database, Pulumi stack, and bind cache are used regardless of which branch you're on.

2. Start Local Development

ds local run

This launches both the backend (Hono, port 3001) and frontend (Vite, port 8080) in a tmux session with side-by-side panes.

tmux navigation:

• Ctrl+B then ← / → — Switch between backend and frontend panes
• Ctrl+B then D — Detach (servers keep running)
• F12 — Quit both servers

3. Write Your Code

Make your changes. If your feature involves:

• New API endpoints: You'll want to regenerate the API client afterwards (see below).
• Database schema changes: Edit the .sql-entity.ts file, then generate and run a migration.
• New Commands or Queries: Use the code generators to scaffold boilerplate.

4. Generate a Migration (If Needed)

If you modified a SQL entity:

# Generate the migration file from your schema changes
cd backend && pnpm generate-sql

# Apply it to your Neon branch
ds db migrate

Then restart your backend server to pick up the schema changes.

5. Generate CQRS Boilerplate (If Needed)

Adding a new command or query? Use the generators:

# Generate a command (e.g., SendNotification in the notification module)
ds local generate command SendNotification -m notification

# Generate a query (e.g., GetUserNotifications in the notification module)
ds local generate query GetUserNotifications -m notification

This creates the command/query artifact, DI init file, service handler, and Lambda handler — all wired up and ready to fill in.

6. Regenerate the API Client

After adding or modifying API endpoints:

ds api generate-api-client

This scans the backend Hono routes and generates a fully-typed TypeScript SDK in frontend/src/api/. The frontend can immediately use the new endpoints with full type safety.

7. Deploy for Cloud Testing

When you're ready to test in an isolated cloud environment:

ds deploy up

Unlike local development (which always uses phil-local), cloud deployments create a branch-specific stage. The CLI computes a stage name from your developer name + branch, then dispatches a GitHub Actions workflow. Each cloud stage gets its own fully isolated AWS resources and Neon database branch.

Dispatching deploy-stage.yml...
Stage: phil-feature-user-notifications
Branch: feature/user-notifications

Building frontend... ✓
Bundling Lambdas... ✓
Running pulumi up... ✓

✓ Deployment complete
  API: https://api-phil-feature-user-notifications.devstride.dev
  UI:  https://app-phil-feature-user-notifications.devstride.dev

8. Clean Up When Done

After your PR is merged:

ds deploy down phil-feature-user-notifications

ds deploy down handles everything: empties S3 buckets, runs pulumi destroy, removes the Pulumi stack, cleans up Secrets Manager entries, and deletes the Neon database branch.

Scenario 2: Daily Development

Not every task needs a feature branch or a cloud deploy. For ongoing work:

Morning Startup

# Pull latest code
git checkout main && git pull

# Start local dev
ds local run

Your local stage (phil-local) persists across sessions and across branch switches. The database branch, infrastructure, and config are all still there from setup — switching to a feature branch and back won't affect them.

After Someone Else Merges Schema Changes

If a teammate's PR included database migrations:

# Pull their changes
git pull

# Run any new migrations
ds db migrate

# Restart backend to pick up schema changes
ds local run backend

Updating Your Cloud Stage

After pulling new code and wanting to see it deployed:

ds deploy up

This is an incremental update — only changed resources are modified. Much faster than the initial deploy.

Scenario 3: Resetting Your Database

Sometimes you need a fresh database — maybe migrations got tangled, or you want clean staging data.

Reset from Main

ds db reset

This resets your Neon branch to match the main branch data, then re-applies migrations. Your connection string stays the same — no .env changes needed. Restart your backend after.

Scenario 4: Working on Multiple Features

Local development always uses your single phil-local stage. But when you need cloud environments for testing or review, ds deploy up creates isolated, branch-specific stages — each with its own AWS resources and Neon database branch.

# Feature A — deploy to cloud
git checkout feature/auth-improvements
ds deploy up
# → Deploys to stage: phil-feature-auth-improvements
# → Neon branch: dev-phil-feature-auth-improvements

# Feature B — deploy to cloud
git checkout feature/gantt-export
ds deploy up
# → Deploys to stage: phil-feature-gantt-export
# → Neon branch: dev-phil-feature-gantt-export

Each cloud stage is fully isolated with its own:

• AWS resources (API Gateway, Lambdas, S3, Cognito)
• Neon database branch (separate from your local dev-phil-local branch)
• Pulumi stack

Meanwhile, ds local run on any of these branches still uses phil-local — your single, stable local environment.

List all your stages:

ds deploy list

Cleaning Up Multiple Stages

When you're done with several stages:

# Interactive cleanup — finds stale stages
ds aws cleanup

# Or tear down specific stages
ds deploy down phil-feature-auth-improvements
ds deploy down phil-feature-gantt-export

ds aws cleanup is especially useful — it scans for stages that haven't been deployed in 14+ days and lets you select which ones to tear down.

Scenario 5: Debugging a Deployed Stage

Your deployed stage is showing errors. Here's how to investigate:

Check Stage Status

ds deploy list --stage phil-local

Shows resource details, URLs, and last activity timestamp.

Check Database Status

ds db status

Shows which Neon branch you're connected to and its health.

Run Health Checks

ds doctor

Verifies tool presence, service access, and local health (.env, database connectivity, Pulumi stack).

Re-deploy After a Fix

# Make your fix locally, test it
ds local run

# Deploy the fix
ds deploy up

Scenario 6: Updating Shared Secrets

A third-party API key has rotated, or a new secret needs to be added.

Pull Latest Secrets

ds setup secrets pull

Downloads the latest shared secrets from AWS Secrets Manager to your .env.

Push a Secret Update

# Edit your .env with the new value, then push
ds setup secrets push

This uploads your .env values back to Secrets Manager so other developers can pull them.

Audit Secrets

ds setup secrets audit

Interactive mode that shows all required/optional secrets with their current status (configured, missing, or placeholder). Guides you through fixing missing values.

Backup and Restore

# Before making risky .env changes
ds setup env backup

# If something goes wrong
ds setup env restore

Quick Reference: Common Workflows

Next Steps

• Local Development — Deep dive into ds local run and code generation
• Database Management — Detailed database operations
• Deployment — Deployment commands and options