How elmarguevarra/visitor-management works
Project Type and Purpose
• This is a full-stack serverless application using AWS SAM.
• Frontend: Vue.js SPA, static assets hosted on S3 + CloudFront.
• Backend: HTTP API (API Gateway) + Lambda functions.
• Data: DynamoDB tables.
• Auth & Security: Cognito User Pool (with Google IdP) + Lambda authorizer + Verified Permissions.
• Infra as Code: AWS SAM template + individual CloudFormation YAMLs under infrastructure/resources.
File Structure
• Top-level folders:
• backend/ (Lambda code, unit tests)
• frontend/ (Vue code, mocks, unit tests)
• infrastructure/ (CloudFormation YAML for API Gateway, Cognito, DynamoDB, S3/CloudFront, DNS, Verified Permissions)
• template.yaml & samconfig.toml (SAM stack definition)
• scripts/ (deploy scripts)
• The backend/src/handlers map one-to-one to Lambda functions defined in template.yaml.
• infrastructure/resources/*.yaml define individual stacks (e.g. CognitoUserPool, API Gateway, DynamoDB tables, S3 bucket + CloudFront distribution, HostedZone).
Them into three layers:
A. Presentation Layer
• User’s Browser (SPA in Vue)
• CloudFront Distribution
• S3 Bucket (static SPA files)
• Route53 Custom Domain & ACM Certificate
B. Business (Compute) Layer
• API Gateway HTTP API
• Lambda Functions (putVisitor, getVisitors, getInviteByToken, getVisitRequestByToken, putVisitRequest, authorizer, jwtVerifier, etc.)
• Cognito User Pool (Hosted UI) + Identity Providers (Google IdP)
• Lambda Authorizer (custom JWT verifier)
• AWS Verified Permissions (fine-grained authorization)
C. Data Layer
• DynamoDB Tables: VisitorsTable, InviteLinksTable (TTL), VisitRequestsTable (TTL)
D. Supporting Infra
• CloudFormation / SAM (template.yaml)
• Deployment pipelines (GitHub Actions, deploy scripts)
Relationships & Data Flows
1. User → CloudFront → S3 (GET SPA assets)
2. User signs in via Cognito Hosted UI → receives JWT
3. SPA calls API Gateway (XHR) with Authorization header
4. API Gateway → Lambda Authorizer → Cognito / Verified Permissions → allow/deny
5. API Gateway → Specific Lambda functions → read/write from DynamoDB
6. DynamoDB → return data to Lambda → API Gateway → SPA
7. (Optional) Route53 & ACM handle domain name resolution and HTTPS termination.
Architectural Patterns & Design Principles
• Serverless micro-services: each handler is its own Lambda.
• IAM-scoped policies: least privilege for each function.
• Infrastructure as Code: AWS SAM + CloudFormation modules under infrastructure/resources.
• SPA + API separation: clear frontend/backend boundary.
• Mock service-worker in frontend for local testing.
• Unit tests co-located under backend/__tests__ and frontend/test.
Final Checklist
• [ ] Frontend: Browser, CloudFront, S3, Route53, ACM
• [ ] Auth: Cognito User Pool, Google IdP, Lambda Authorizer, Verified Permissions
• [ ] API: API Gateway HTTP API → Lambda functions (grouped by directory: auth vs. CRUD)
• [ ] Data: DynamoDB tables (with TTL shown)
• [ ] Infra: AWS SAM / CloudFormation (template.yaml + YAMLs)
• [ ] Labels on every component