# coffeey0128/auto-punch-terraform architecture

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

- Interactive diagram: https://gitdiagram.com/coffeey0128/auto-punch-terraform
- Repository: https://github.com/coffeey0128/auto-punch-terraform

## Overview

##### Project Type and Purpose
- This is a serverless, event-driven automation system built and managed entirely with Terraform.
- Its goal is to automatically “punch in/out” (打卡) for a user by invoking the mobile app’s APIs on a schedule, with randomization and holiday checks.

##### File Structure Analysis
- Top-level Terraform files (`main.tf`, `lambda.tf`, `sqs.tf`, `sns.tf`, `event_bridge.tf`, `iam.tf`, etc.) declare and configure AWS resources.
- `resources/random-time/` and `resources/auto-punch/` each contain a Lambda function’s code and `package.json`.
- No traditional frontend/backend or database layers—this is pure infra + serverless functions.

##### Key README Insights
- Flow: EventBridge → “random-time” Lambda → SQS (delayed) → “auto-punch” Lambda → SNS Topic → Email.
- AWS services used: EventBridge (scheduler), SQS (delayed queue), Lambda (compute), SNS (notification).
- Terraform is the deployment mechanism.

##### Main Components
a. Infrastructure as Code layer
- Terraform CLI & State (manages all AWS resources)
b. AWS Accounts/Region boundary
c. EventBridge Scheduler (cron-like trigger)
d. Lambda “random-time” (computes a random delay window and pushes a message to SQS with DelaySeconds)
e. SQS Queue (holds the delayed message until release)
f. Lambda “auto-punch” (consumes the SQS message, checks holidays, calls punch APIs)
g. SNS Topic (receives success/failure result)
h. Email Subscription (user’s inbox)

##### Component Interactions and Data Flow
1. Terraform applies, creating all AWS components.
2. EventBridge fires on a fixed schedule (e.g. every weekday 08:55).
3. EventBridge → invokes Lambda(random-time).
4. Lambda(random-time) → SendMessage to SQS with randomized DelaySeconds.
5. SQS holds message until delay expires.
6. SQS triggers Lambda(auto-punch).
7. Lambda(auto-punch):
- Calls the holiday API; if today is holiday or on personal leave, skip.
- Otherwise, calls the login/refresh API + punch API with stored PID/CID/TOKEN, device ID & coordinates.
- Publishes result (success/failure) to SNS topic.
8. SNS → Email subscription → notifies user.

##### Architectural Patterns and Principles
- Serverless micro-services pattern: each Lambda is single-purpose.
- Event-driven choreography: EventBridge, SQS, SNS as decouplers.
- Infrastructure-as-Code: Terraform modules define all AWS resources, IAM roles, permissions.
- Security principle: Least privilege IAM for each Lambda → SQS & SNS.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Infrastructure as Code Layer
    subgraph "Infrastructure as Code"
        direction TB
        TF_Main["main.tf"]:::infra
        TF_Lambda["lambda.tf"]:::infra
        TF_SQS["sqs.tf"]:::infra
        TF_SNS["sns.tf"]:::infra
        TF_EventBridge["event_bridge.tf"]:::infra
        TF_IAM["iam.tf"]:::infra
    end

    %% AWS Account Boundary
    subgraph "AWS Account / Region"
        direction TB
        EB["EventBridge Scheduler\n(cron trigger)"]:::infra
        RL["Lambda: random-time\n(compute random DelaySeconds)"]:::compute
        SQS["SQS Queue\nDelaySeconds=random interval"]:::messaging
        AP["Lambda: auto-punch\nholiday API → skip logic\npunch API calls"]:::compute
        SNS["SNS Topic\nEmail subscription"]:::notification
        EMAIL["Email Subscription"]:::external
        IAM["IAM Roles & Policies"]:::infra
    end

    %% Terraform provisioning arrows
    TF_EventBridge --> EB
    TF_Lambda --> RL
    TF_Lambda --> AP
    TF_SQS --> SQS
    TF_SNS --> SNS
    TF_IAM --> IAM
    TF_Main -.-> EB
    TF_Main -.-> RL
    TF_Main -.-> SQS
    TF_Main -.-> AP
    TF_Main -.-> SNS

    %% Data Flow
    EB -->|"invokes"| RL
    RL -->|"SendMessage"| SQS
    SQS -->|"triggers"| AP
    AP -->|"PublishResult"| SNS
    SNS -->|"delivers"| EMAIL

    %% Click Events
    click TF_Main "https://github.com/coffeey0128/auto-punch-terraform/blob/main/main.tf"
    click TF_Lambda "https://github.com/coffeey0128/auto-punch-terraform/blob/main/lambda.tf"
    click TF_SQS "https://github.com/coffeey0128/auto-punch-terraform/blob/main/sqs.tf"
    click TF_SNS "https://github.com/coffeey0128/auto-punch-terraform/blob/main/sns.tf"
    click TF_EventBridge "https://github.com/coffeey0128/auto-punch-terraform/blob/main/event_bridge.tf"
    click TF_IAM "https://github.com/coffeey0128/auto-punch-terraform/blob/main/iam.tf"
    click RL "https://github.com/coffeey0128/auto-punch-terraform/blob/main/resources/random-time/index.js"
    click RL "https://github.com/coffeey0128/auto-punch-terraform/blob/main/resources/random-time/package.json"
    click AP "https://github.com/coffeey0128/auto-punch-terraform/blob/main/resources/auto-punch/index.js"
    click AP "https://github.com/coffeey0128/auto-punch-terraform/blob/main/resources/auto-punch/package.json"

    %% Styling
    classDef infra fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef compute fill:#FFA500,stroke:#333,stroke-width:1px
    classDef messaging fill:#FFFF00,stroke:#333,stroke-width:1px
    classDef notification fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef external fill:#CCCCCC,stroke:#333,stroke-width:1px
```
