# whyphi/zap architecture

> Architecture diagram of the GitHub repository whyphi/zap, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/whyphi/zap
- Repository: https://github.com/whyphi/zap

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Client["External Clients (Web/Mobile)"]:::client
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        APIGW["API Gateway"]:::api
    end

    %% Compute Layer
    subgraph "Compute Layer"
        direction TB
        Lambda["AWS Lambda (Chalice)"]:::compute

        subgraph "Application Layer"
            direction TB
            AppPy["app.py"]:::app
            subgraph "API Handlers"
                direction TB
                A1["accountability.py"]:::apiHandler
                A2["announcements.py"]:::apiHandler
                A3["applicants.py"]:::apiHandler
                A4["events_member.py"]:::apiHandler
                A5["events_rush.py"]:::apiHandler
                A6["insights.py"]:::apiHandler
                A7["listings.py"]:::apiHandler
                A8["members.py"]:::apiHandler
                A9["monitoring.py"]:::apiHandler
            end
            subgraph "Service Layer"
                direction TB
                S1["AccountabilityService.py"]:::service
                S2["ApplicantService.py"]:::service
                S3["EventsMemberService.py"]:::service
                S4["EventsRushService.py"]:::service
                S5["InsightsService.py"]:::service
                S6["ListingService.py"]:::service
                S7["MemberService.py"]:::service
                S8["MonitoringService.py"]:::service
            end
            subgraph "Data Models"
                direction TB
                M1["application.py"]:::model
                M2["listing.py"]:::model
                M3["roles.py"]:::model
            end
            subgraph "Integration Modules"
                direction TB
                IM1["aws_ssm.py"]:::integration
                IM2["ses.py"]:::integration
                IM3["google_sheets.py"]:::integration
                IM4["mongo.py"]:::integration
                IM5["s3.py"]:::integration
            end
            Decorators["decorators.py"]:::crosscut
            ErrorHandler["error_handler.py"]:::crosscut
            DBInit["db.py"]:::config
            Utils["utils.py"]:::util
            Validator["validators/listings.py"]:::util
        end
    end

    %% Data & External Services
    subgraph "Data Layer"
        direction TB
        DynamoDB["DynamoDB Tables"]:::data
        S3Bucket["S3 Bucket"]:::data
    end

    subgraph "External Integrations"
        direction TB
        SES["AWS SES"]:::external
        SSM["SSM Parameter Store"]:::external
        Sheets["Google Sheets API"]:::external
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        GH["GitHub"]:::cicd
        Actions["GitHub Actions"]:::cicd
        Deploy["Chalice Deployment"]:::cicd
    end

    %% Connections
    Client -->|HTTPS Request| APIGW
    APIGW -->|Invoke| Lambda
    Lambda --> AppPy
    AppPy --> A1
    AppPy --> A2
    AppPy --> A3
    AppPy --> A4
    AppPy --> A5
    AppPy --> A6
    AppPy --> A7
    AppPy --> A8
    AppPy --> A9

    A1 --> S1
    A2 --> S2
    A3 --> S3
    A4 --> S4
    A5 --> S4
    A6 --> S5
    A7 --> S6
    A8 --> S7
    A9 --> S8

    S1 --> M1
    S2 --> M1
    S3 --> M1
    S4 --> M1
    S5 --> M2
    S6 --> M2
    S7 --> M3
    S8 --> M3

    S1 --> IM1
    S2 --> IM4
    S3 --> IM4
    S4 --> IM4
    S5 --> IM3
    S6 --> IM5
    S7 --> IM2
    S8 --> IM1

    IM1 --> SSM
    IM2 --> SES
    IM3 --> Sheets
    IM4 --> DynamoDB
    IM5 --> S3Bucket

    S1 -->|Uses| Decorators
    S2 -->|Uses| Decorators
    S3 -->|Uses| Decorators
    S4 -->|Uses| Decorators
    S5 -->|Uses| Decorators
    S6 -->|Uses| Decorators
    S7 -->|Uses| Decorators
    S8 -->|Uses| Decorators

    A1 -->|Errors| ErrorHandler
    A2 -->|Errors| ErrorHandler
    A3 -->|Errors| ErrorHandler
    A4 -->|Errors| ErrorHandler
    A5 -->|Errors| ErrorHandler
    A6 -->|Errors| ErrorHandler
    A7 -->|Errors| ErrorHandler
    A8 -->|Errors| ErrorHandler
    A9 -->|Errors| ErrorHandler

    AppPy -->|Init DB| DBInit
    AppPy --> Utils
    S6 --> Validator

    GH --> Actions
    Actions --> Deploy
    Deploy --> APIGW
    Deploy --> Lambda

    %% Click Events
    click AppPy "https://github.com/whyphi/zap/blob/main/app.py"
    click A1 "https://github.com/whyphi/zap/blob/main/chalicelib/api/accountability.py"
    click A2 "https://github.com/whyphi/zap/blob/main/chalicelib/api/announcements.py"
    click A3 "https://github.com/whyphi/zap/blob/main/chalicelib/api/applicants.py"
    click A4 "https://github.com/whyphi/zap/blob/main/chalicelib/api/events_member.py"
    click A5 "https://github.com/whyphi/zap/blob/main/chalicelib/api/events_rush.py"
    click A6 "https://github.com/whyphi/zap/blob/main/chalicelib/api/insights.py"
    click A7 "https://github.com/whyphi/zap/blob/main/chalicelib/api/listings.py"
    click A8 "https://github.com/whyphi/zap/blob/main/chalicelib/api/members.py"
    click A9 "https://github.com/whyphi/zap/blob/main/chalicelib/api/monitoring.py"
    click S1 "https://github.com/whyphi/zap/blob/main/chalicelib/services/AccountabilityService.py"
    click S2 "https://github.com/whyphi/zap/blob/main/chalicelib/services/ApplicantService.py"
    click S3 "https://github.com/whyphi/zap/blob/main/chalicelib/services/EventsMemberService.py"
    click S4 "https://github.com/whyphi/zap/blob/main/chalicelib/services/EventsRushService.py"
    click S5 "https://github.com/whyphi/zap/blob/main/chalicelib/services/InsightsService.py"
    click S6 "https://github.com/whyphi/zap/blob/main/chalicelib/services/ListingService.py"
    click S7 "https://github.com/whyphi/zap/blob/main/chalicelib/services/MemberService.py"
    click S8 "https://github.com/whyphi/zap/blob/main/chalicelib/services/MonitoringService.py"
    click M1 "https://github.com/whyphi/zap/blob/main/chalicelib/models/application.py"
    click M2 "https://github.com/whyphi/zap/blob/main/chalicelib/models/listing.py"
    click M3 "https://github.com/whyphi/zap/blob/main/chalicelib/models/roles.py"
    click IM1 "https://github.com/whyphi/zap/blob/main/chalicelib/modules/aws_ssm.py"
    click IM2 "https://github.com/whyphi/zap/blob/main/chalicelib/modules/ses.py"
    click IM3 "https://github.com/whyphi/zap/blob/main/chalicelib/modules/google_sheets.py"
    click IM4 "https://github.com/whyphi/zap/blob/main/chalicelib/modules/mongo.py"
    click IM5 "https://github.com/whyphi/zap/blob/main/chalicelib/s3.py"
    click DBInit "https://github.com/whyphi/zap/blob/main/chalicelib/db.py"
    click ErrorHandler "https://github.com/whyphi/zap/blob/main/chalicelib/handlers/error_handler.py"
    click Decorators "https://github.com/whyphi/zap/blob/main/chalicelib/decorators.py"
    click Utils "https://github.com/whyphi/zap/blob/main/chalicelib/utils.py"
    click Validator "https://github.com/whyphi/zap/blob/main/chalicelib/validators/listings.py"
    click GH "https://github.com/whyphi/zap/blob/main/.github"
    click Actions "https://github.com/whyphi/zap/blob/main/.github/workflows/coverage.yml"
    click Actions "https://github.com/whyphi/zap/blob/main/.github/workflows/deploy.yml"
    click GH "https://github.com/whyphi/zap/blob/main/.github/release.yml"

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:1px
    classDef api fill:#bbf,stroke:#333,stroke-width:1px
    classDef compute fill:#ccf,stroke:#333,stroke-width:1px
    classDef app fill:#ddf,stroke:#333,stroke-width:1px
    classDef apiHandler fill:#eef,stroke:#333,stroke-width:1px
    classDef service fill:#cfc,stroke:#333,stroke-width:1px
    classDef model fill:#cff,stroke:#333,stroke-width:1px
    classDef integration fill:#fcf,stroke:#333,stroke-width:1px
    classDef crosscut fill:#fdd,stroke:#333,stroke-width:1px
    classDef config fill:#dfd,stroke:#333,stroke-width:1px
    classDef util fill:#ffd,stroke:#333,stroke-width:1px
    classDef data fill:#afa,stroke:#333,stroke-width:1px
    classDef external fill:#faf,stroke:#333,stroke-width:1px
    classDef cicd fill:#ddd,stroke:#333,stroke-width:1px
```
