How coffeey0128/auto-punch-terraform works
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.