If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Miserlou/Zappa shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 15 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 3y ago
• ⚠ Concentrated ownership — top contributor handles 69% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Miserlou/Zappa repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Miserlou/Zappa.

What it runs against: a local clone of Miserlou/Zappa — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Miserlou/Zappa | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1171 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Miserlou/Zappa. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Miserlou/Zappa.git
#   cd Zappa
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Miserlou/Zappa and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Miserlou/Zappa(\\.git)?\\b" \\
  && ok "origin remote is Miserlou/Zappa" \\
  || miss "origin remote is not Miserlou/Zappa (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "setup.py" \\
  && ok "setup.py" \\
  || miss "missing critical file: setup.py"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "example/zappa_settings.json" \\
  && ok "example/zappa_settings.json" \\
  || miss "missing critical file: example/zappa_settings.json"
test -f "requirements.txt" \\
  && ok "requirements.txt" \\
  || miss "missing critical file: requirements.txt"
test -f "example/app.py" \\
  && ok "example/app.py" \\
  || miss "missing critical file: example/app.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1171 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1141d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Miserlou/Zappa"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Zappa is a serverless Python web framework that deploys WSGI applications (Flask, Django, etc.) directly to AWS Lambda and API Gateway without managing infrastructure. It packages your Python app, handles cold starts, manages environment configuration, and provides CLI tooling to streamline the entire serverless deployment pipeline on AWS. Single monolithic package structure: zappa/ directory contains the core deployment engine (Zappa class), CLI handlers, and AWS integration logic. Tests live in tests/ with data fixtures in tests/data/ and mocked AWS responses in tests/placebo/. Example WSGI apps in example/ (app.py, authmodule.py, mymodule.py) demonstrate real-world usage patterns. Configuration is declarative (zappa_settings.json in example/).

Python web developers who want to deploy Flask/Django applications to AWS Lambda without learning infrastructure-as-code or managing EC2 instances. DevOps engineers adopting serverless who need a batteries-included deployment tool that abstracts AWS complexity.

Mature but transitioning: the original Miserlou/Zappa repository (515KB Python code, comprehensive test suite with placebo mocks, CI via Travis CI) was the foundational implementation. However, the README states the project has moved to https://github.com/zappa/Zappa after v0.52.0, and this archive repo is no longer the active source. The codebase shows solid maturity (extensive tests in tests/ directory, documented examples in example/app.py, policy templates) but is now in maintenance mode on this fork.

Moderate risk: active maintenance has migrated to the zappa/Zappa GitHub organization, so this Miserlou fork receives no new features. The codebase has a single-maintainer history (Rich Jones, per README). AWS Lambda and API Gateway are moving targets—dependencies like boto3 may need updates. No evidence of recent commits or issue triage in the provided file snapshot.

This repository is archived—no active development. The project moved to https://github.com/zappa/Zappa for versions >0.52.0. This snapshot shows the last state before the migration, with no pending changes visible in the file list.

git clone https://github.com/Miserlou/Zappa.git && cd Zappa && pip install -r requirements.txt && pip install -r test_requirements.txt && python -m pytest tests/

Daily commands: For testing: bash test.sh or python -m pytest tests/. For deployment (after setup): zappa deploy <environment> (command-line tool entry point defined in setup.py). For local example: cd example && python app.py (runs Flask dev server).

• setup.py — Project metadata, dependencies, and package configuration—defines what Zappa is and how it's installed.
• README.md — Project overview and migration notice showing that active development moved to zappa/Zappa repository.
• example/zappa_settings.json — Configuration template showing the expected format and options for deploying serverless Python applications.
• requirements.txt — Production dependencies including Flask and zappa itself—defines the runtime environment.
• example/app.py — Reference Flask application demonstrating how to structure a Zappa-deployable serverless app.
• test_settings.json — Test configuration showing how deployment settings are validated and tested.

• Flask Application (Flask, Python stdlib) — Routes HTTP requests, implements business logic, returns JSON/HTML responses.
  • Failure mode: Unhandled exceptions cause 500 errors; missing imports fail at Lambda init time.
• Zappa Runtime Wrapper (Python, botocore) — Adapts AWS Lambda event format to WSGI request; marshals response back to API Gateway.
  • Failure mode: Event parsing errors or WSGI incompatibilities cause invocation failures; timeouts at 15 minutes.
• CloudFormation Stack (CloudFormation (JSON/YAML), AWS IAM) — Creates and manages Lambda function, API Gateway REST API, IAM execution role, and related resources.
  • Failure mode: Stack creation/update failures prevent deployment; rollback on error can lose state.
• Configuration (zappa_settings.json) (JSON) — Defines deployment target, environment variables, VPC, memory, timeout, layers, and logging.
  • Failure mode: Invalid settings cause CLI errors; incorrect IAM policy blocks deployment.

• example/app.py → example/zappa_settings.json — App code is packaged and deployed according to settings (stage, region, runtime, environment).
• example/zappa_settings.json → setup.py / requirements.txt — Settings reference environment variables and custom environment that depend on installed packages.
• requirements.txt / example/requirements.txt → AWS Lambda — All dependencies are zipped with app code and uploaded to Lambda function.
• AWS API Gateway → Lambda (via Zappa wrapper) — HTTP event is translated to WSGI environ dict and passed to Flask app.
• Flask app → AWS API Gateway — Response status, headers, and body are marshaled back to API Gateway format and returned to client.
• example/policy/deploy.json → IAM Role (CloudFormation) — IAM policy grants Lambda permission to write logs, call API Gateway, access VPC, etc.

Create a new Zappa-deployable Flask endpoint

1. Add route handler to the Flask app (example/app.py)
2. Add any custom business logic to modules (example/mymodule.py)
3. Add required Python dependencies to requirements (example/requirements.txt)
4. Configure deployment stage in zappa_settings.json (example/zappa_settings.json)

Add AWS deployment configuration

1. Create or edit zappa_settings.json with stage-specific options (runtime, environment variables, VPC, etc.) (example/zappa_settings.json)
2. Define IAM policy for deployment permissions (example/policy/deploy.json)
3. Add environment-specific settings in zappa_settings.json stages (example/zappa_settings.json)

Add test cases for deployments

1. Define test scenarios in name_scenarios.json (tests/name_scenarios.json)
2. Create test data modules in tests/data/ (tests/data/test1.py)
3. Add test configuration to test_settings.json (test_settings.json)
4. Run tests with recorded AWS responses from placebo directory (tests/placebo/TestZappa.test_cli_aws)

• AWS Lambda + API Gateway — Serverless compute for Python applications without managing infrastructure; scales automatically and charges per invocation.
• CloudFormation — Infrastructure-as-code for reproducible deployments of Lambda, API Gateway, IAM roles, and other AWS resources.
• Flask — Lightweight WSGI framework that Zappa adapts to work in Lambda's event-driven model by translating API Gateway events to HTTP requests.
• Placebo (mocked AWS responses) — Enables deterministic testing without hitting real AWS APIs; recordings are checked into version control for reproducible test runs.

• Single-stage Flask app deployment model

  • Why: Simplifies configuration for most use cases; one code base handles all HTTP requests.
  • Consequence: Complex routing logic must live in Flask; no built-in multi-handler patterns like separate Lambda functions per route.

• CloudFormation for infrastructure management

  • Why: Declarative, version-controlled infrastructure; integrates with AWS console and other tools.
  • Consequence: Stack updates can fail or rollback; requires understanding CF error messages; slower iteration than imperative CLI tools.

• Zipped Python package deployment

  • Why: Avoids real-time compilation; self-contained artifact that Lambda can execute immediately.
  • Consequence: Large dependency trees (e.g., NumPy, pandas) exceed Lambda's 250MB uncompressed limit; requires layer splitting or optimization.

• Does not handle real-time streaming or long-lived WebSocket connections (Lambda has 15-minute timeout).
• Does not provide managed relational database solutions (developers must configure RDS separately).
• Does not abstract away AWS service quotas, regional limitations, or billing intricacies.
• Does not support non-Python runtimes (Zappa is Python-specific).
• Does not manage CI/CD pipelines beyond CloudFormation stack deployment.

• Monolithic Flask app in single file (Low) — example/app.py: All routes, logic, and configuration in one module; makes testing and refactoring difficult as app grows.
• Credentials in zappa_settings.json (High) — example/zappa_settings.json: Should use environment variables or AWS Secrets Manager, not hardcoded secrets in version control.
• Placebo recordings not updated with schema changes: undefined

1. This is a stale archive fork—new code goes to zappa/Zappa, so PRs here may not merge. 2) AWS credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY) required for non-test deployments. 3) Placebo mocks in tests/placebo/ are recorded responses; new AWS API changes may break them. 4) zappa_settings.json uses environment-specific keys (e.g., 'dev', 'prod') that must match deployment targets. 5) Lambda's 250MB uncompressed package limit requires careful dependency pruning—not enforced in code, only at deploy time.

• WSGI (Web Server Gateway Interface) — Zappa's core function is translating AWS Lambda events into WSGI-compatible environ dicts; understanding WSGI is mandatory to debug request routing
• Lambda Cold Starts & Warm Starts — Zappa mitigates cold starts via keepalive pings and package optimization; understanding this tradeoff is critical for production deployment decisions
• AWS API Gateway Event Format (Lambda Proxy Integration) — Zappa converts incoming API Gateway proxy events into WSGI environ; reading the event structure is necessary to understand request handling
• Environment Variable Injection & Secrets Management — Zappa allows per-environment AWS Systems Manager Parameter Store / Secrets Manager injection via zappa_settings.json; mishandling leaks secrets or breaks deployments
• Lambda Layers & VPC Networking — Zappa supports Lambda Layers for shared dependencies and VPC attachment for database access; these are non-obvious deployment options affecting architecture decisions
• Placebo (AWS Response Recording/Mocking) — Tests use placebo to record and replay boto3 calls offline; understanding this pattern is essential to add or modify deployment tests without AWS credentials
• IAM Policy Principle of Least Privilege — Zappa deployments require fine-grained IAM permissions (Lambda, API Gateway, CloudWatch, S3, etc.); example/policy/deploy.json shows required permissions—overly broad policies are a security risk

• zappa/Zappa — The active successor to this archived fork; all new development, security patches, and v0.52.0+ releases are here
• serverless/serverless — Alternative serverless deployment framework supporting multiple languages and providers; if you outgrow Python-only or want multi-cloud
• aws/chalice — AWS's official serverless Python microframework; lighter than Zappa but tighter AWS integration for greenfield projects
• aws/aws-lambda-powertools-python — Official AWS Lambda utilities for Python (logging, tracing, data validation); commonly used alongside Zappa for observability
• pallets/flask — Primary WSGI framework target for Zappa; understanding Flask middleware and request context is essential for customization

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test coverage for placebo-recorded API Gateway scenarios

The repo has extensive placebo recordings in tests/placebo/TestZappa.test_cli_aws/ (40+ JSON files for API Gateway operations like CreateResource, CreateDeployment, UpdateStage) but the actual test implementations appear minimal. New contributors could expand test_settings.json and tests/ to validate these recorded scenarios cover critical paths: multi-resource creation, deployment stages, API key management, and error cases. This would catch regressions in AWS API interactions without live calls.

• [ ] Review tests/placebo/TestZappa.test_cli_aws/ to identify which API operations lack corresponding test assertions
• [ ] Extend tests/init.py or create tests/test_api_gateway.py with parameterized tests for each placebo recording
• [ ] Add assertions for resource hierarchy (e.g., CreateResource_1 through _9 should form proper parent-child relationships)
• [ ] Document expected behavior in tests/README.md for placebo test patterns

Create migration guide and update example/ for post-0.52.0 repository

The README.md explicitly states the project moved to github.com/zappa/Zappa after version 0.52.0, but example/zappa_settings.json and example/requirements.txt still reference this old repo. New contributors should update example/ to reflect current best practices and add a MIGRATION.md guide documenting how users on old versions should upgrade, including breaking changes between 0.52.0 and current versions.

• [ ] Update example/requirements.txt to point to the new repository and include version constraints
• [ ] Revise example/zappa_settings.json with modern configuration options (check against new repo's documentation)
• [ ] Create docs/MIGRATION_FROM_OLD_REPO.md explaining upgrade path, deprecated settings, and new features since fork
• [ ] Update example/README.md with warning about using the archived repo and links to active maintainers

Add unit tests for test data module validation in tests/data/

The tests/data/ directory contains test1.py, test1/this_dir_is_not_a_module.txt, and test2/test.py (used for module discovery/loading tests), but there are no visible assertions validating the module import system handles these edge cases correctly. New contributors should create tests/test_module_discovery.py with specific tests for: valid module detection, directory exclusion (non-modules), nested module structures, and missing init.py scenarios.

• [ ] Create tests/test_module_discovery.py with test functions for each edge case in tests/data/
• [ ] Add test for verifying test1/this_dir_is_not_a_module.txt is correctly excluded from module loading
• [ ] Add test for proper handling of test1.py vs test2/test.py module precedence and imports
• [ ] Document the purpose of each test data fixture in tests/README.md

• Add tests for zappa/utilities.py functions (helpers for file handling, ZipFile creation) which appear untested based on missing test_utilities.py; start by writing unit tests mirroring example patterns in tests/test_core.py
• Document the complete zappa_settings.json schema in docs/ (e.g., docs/settings-reference.md) by extracting all keys from example/zappa_settings.json and cross-referencing zappa/core.py defaults
• Add a missing test file tests/test_wsgi.py with cases for WSGI environ dict construction from API Gateway Lambda events—critical path but no dedicated test file visible

This codebase has significant security concerns primarily related to severely outdated dependencies (Flask 0.12 from 2017) and use of a deprecated project. The main risks include exposure to known vulnerabilities in Flask and its dependencies, lack of security header configuration, and dependency management issues. The project is explicitly marked as deprecated in favor of a new repository location, which compounds the security risk. Immediate action required: update Flask to v2.3+ or v3.x, pin Zappa to a specific version or migrate to the active repository, and implement security headers. The security score of 42/100 reflects

• High · Outdated Flask Dependency — requirements.txt, requirements.in. The requirements.txt specifies Flask>=0.12, which is extremely outdated. Flask 0.12 was released in 2017 and contains numerous known security vulnerabilities including potential issues with Werkzeug, session handling, and HTTP header parsing. Current Flask versions are 2.x and 3.x. Fix: Update Flask to a recent stable version (Flask>=2.3.0 or latest 3.x). Review and update all transitive dependencies as well. Run 'pip-audit' to identify known vulnerabilities.
• High · Unspecified Zappa Version Vulnerability Risk — requirements.txt. The requirements specify 'zappa>=0.17.6' without an upper bound. The README indicates this repository is deprecated (versions after 0.52.0 are published from a new location). Using an indefinite version range with a deprecated package could lead to compatibility issues and security gaps. Fix: Pin Zappa to a specific known-good version (e.g., 'zappa==0.52.0') or migrate to the active Zappa repository. Use version pinning for production deployments rather than range specifications.
• Medium · Missing Security Headers Configuration — example/app.py. The example Flask application in 'example/app.py' does not show any security header configuration (Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, etc.), which is critical for serverless web applications. Fix: Add security headers middleware to Flask application. Implement using Flask extensions like Flask-Talisman or manually add headers in after_request handlers. Example: app.config['SESSION_COOKIE_SECURE'] = True, app.config['SESSION_COOKIE_HTTPONLY'] = True
• Medium · Potential Dependency Resolution Issues — requirements.txt, requirements.in, test_requirements.txt, test_requirements.in. The codebase uses both 'requirements.txt' and 'requirements.in' without clear documentation. Additionally, 'test_requirements.txt' and 'test_requirements.in' exist separately. Inconsistent dependency management can lead to unpredictable behavior and missed security patches. Fix: Use pip-tools or Poetry for dependency management. Ensure all environments use the same pinned versions. Document the build process clearly in README.
• Low · Test Configuration Exposed — test_settings.json, test_settings.py. The presence of 'test_settings.json' and 'test_settings.py' files may contain test credentials or sensitive configuration that should not be in version control. Fix: Move test credentials to environment variables or use a test-specific secrets manager. Add test settings files to .gitignore if they contain any sensitive data. Use fixtures or factories for test data.
• Low · Example Configuration Policy Not Reviewed — example/policy/deploy.json. The example AWS IAM policy in 'example/policy/deploy.json' should be reviewed to ensure it follows the principle of least privilege. Overly permissive example policies can be copy-pasted into production. Fix: Review and document the minimum required IAM permissions. Provide clear warnings in documentation about restricting permissions for production use. Include resource ARN restrictions and action limitations.
• Low · Deprecated Repository Notice — README.md. The README explicitly states the project has moved and this repository is no longer maintained. Using dependencies from a deprecated/unmaintained project increases security risk due to lack of security updates. Fix: Migrate to the active Zappa repository at https://github.com/zappa/Zappa. Update all references and consider a full dependency audit with the new maintainers.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.