How whyphi/zap works
Project type and purpose
• Zap is a serverless REST API built with AWS Chalice.
• It provides endpoints for soro’s “accountability,” “announcements,” “applicants,” “events,” “insights,” “listings,” and “members” features.
• Under the hood it uses AWS Lambda (via Chalice), API Gateway, DynamoDB, S3, SES, SSM Parameter Store, and integrates with Google Sheets.
File structure
• Top-level:
• .chalice/ – Chalice configuration and per-environment (dev/prod) deployment settings.
• app.py – Chalice app entrypoint defining routes.
• chalicelib/ – core application code, organized into subpackages:
– api/ – route handlers (one module per resource).
– services/ – business logic classes (one per feature).
– models/ – data schemas (application, listing, roles).
– modules/ – integration wrappers for AWS SSM, SES, S3, DynamoDB/Mongo, Google Sheets.
– db.py – DynamoDB client initialization.
– handlers/ – error handling.
– decorators.py – auth or validation decorators.
– utils.py & validators/ – helpers and input validation.
• Tests mirror api/ and services/ structure under tests/.
Key insights from README
• Deployment flow: GitHub Actions → Chalice → Lambda/API Gateway.
• Environments: dev, staging, prod.
• Local dev via chalice local.
• Uses AWS-managed services for persistence, config and notifications.
a. Client Layer
• External clients (Web/Mobile) making HTTPS calls.
b. API Layer
• AWS API Gateway (REST endpoint per environment).
c. Compute Layer
• AWS Lambda functions (packaged by Chalice).
• Single Lambda or per-route invocations.
d. Application Layer (inside Lambda)
• Request flows from app.py → api/ handlers → services/ → modules/ → models/db.
• Cross-cutting decorators (auth/validation), error handler.
e. Data Layer
• AWS DynamoDB tables.
• AWS S3 buckets (for file storage).
f. Integration & Configuration
• AWS SSM Parameter Store (for secrets/config).
• AWS SES (for email notifications).
• External Google Sheets API.
g. CI/CD Pipeline
• GitHub Actions workflows: test coverage, deploy to dev/staging/prod.
Relationships & interactions
• Inside Lambda: API handlers invoke Services, which read/write Models and call Modules.
• Services → DynamoDB (CRUD).
• Services → S3 (upload/download).
• Services → SES (send emails).
• Services → SSM (fetch config).
• Services → Google Sheets (read/write).
• GitHub → Actions → Chalice deploy → API Gateway & Lambda.
Architectural patterns & design principles
• Layered architecture:
• API Layer (routing)
• Service Layer (business logic)
• Data/Integration Layer (modules)
• Single-responsibility per module and service.
• Serverless micro-function pattern (each route is a function).
• Infrastructure as code via Chalice config.
• Automated CI/CD promoting dev → staging → prod.