# elmarguevarra/visitor-management architecture

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

- Interactive diagram: https://gitdiagram.com/elmarguevarra/visitor-management
- Repository: https://github.com/elmarguevarra/visitor-management

## Overview

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

## Diagram (Mermaid)

```mermaid
graph TB
  %% Presentation Layer
  subgraph "Presentation Layer"
    direction TB
    Browser["User Browser"]:::presentation
    DNS["Route53 DNS"]:::presentation
    ACM["ACM Certificate"]:::presentation
    CloudFront["CloudFront Distribution"]:::presentation
    S3["S3 Bucket (Static SPA)"]:::presentation
  end

  %% Business Layer
  subgraph "Business Layer"
    direction TB
    Cognito["Cognito User Pool (Hosted UI)"]:::compute
    GoogleIdP["Google Identity Provider"]:::compute
    Authorizer["Lambda Authorizer"]:::compute
    VerifiedPerm["Verified Permissions"]:::compute
    API["API Gateway HTTP API"]:::compute
    subgraph "Lambda Functions"
      direction TB
      AuthVerifier["jwtVerifier.mjs"]:::compute
      AuthAuthorizer["authorizer.mjs"]:::compute
      GetInviteByToken["get-invite-by-token.mjs"]:::compute
      GetVisitReqByToken["get-visit-request-by-token.mjs"]:::compute
      GetVisitors["get-visitors.mjs"]:::compute
      GetVisitorById["get-visitor-by-id.mjs"]:::compute
      GetVisitRequests["get-visit-requests.mjs"]:::compute
      PutInviteLink["put-invite-link.mjs"]:::compute
      PutVisitRequest["put-visit-request.mjs"]:::compute
      PutVisitor["put-visitor.mjs"]:::compute
      Utils["utils.mjs"]:::compute
    end
  end

  %% Data Layer
  subgraph "Data Layer"
    direction TB
    VisitorsTable["VisitorsTable (DynamoDB)"]:::data
    InviteLinksTable["InviteLinksTable (TTL)"]:::data
    VisitRequestsTable["VisitRequestsTable (TTL)"]:::data
  end

  %% Infrastructure & CI
  subgraph "Infrastructure & CI"
    direction TB
    SAM["template.yaml & samconfig.toml"]:::infra
    CFN["infrastructure/resources/*.yaml"]:::infra
    DeployBackend["scripts/deploy_backend_and_infra.sh"]:::infra
    DeployFrontend["scripts/deploy_frontend.sh"]:::infra
    CICD[".github/workflows/deploy.yml"]:::infra
  end

  %% Connections - Presentation to Business
  Browser -->|"HTTPS GET SPA"| CloudFront
  CloudFront -->|"Fetch Static Assets"| S3
  Browser -->|"DNS Lookup"| DNS
  DNS --> CloudFront
  DNS --> ACM
  ACM --> CloudFront

  Browser -->|"HTTPS REST (JWT)"| API

  %% Auth Flow
  API -->|"Invoke Authorizer"| Authorizer
  Authorizer -->|"Verify JWT"| AuthVerifier
  Authorizer -->|"Fetch Permissions"| VerifiedPerm
  Authorizer --> Cognito
  Cognito --> GoogleIdP

  %% API to Lambdas
  API --> GetInviteByToken
  API --> GetVisitReqByToken
  API --> GetVisitors
  API --> GetVisitorById
  API --> GetVisitRequests
  API --> PutInviteLink
  API --> PutVisitRequest
  API --> PutVisitor

  %% Lambda to Data
  GetInviteByToken --> InviteLinksTable
  GetVisitReqByToken --> VisitRequestsTable
  GetVisitRequests --> VisitRequestsTable
  GetVisitors --> VisitorsTable
  GetVisitorById --> VisitorsTable
  PutInviteLink --> InviteLinksTable
  PutVisitRequest --> VisitRequestsTable
  PutVisitor --> VisitorsTable

  %% Response Flows
  VisitorsTable --> GetVisitors
  VisitorsTable --> GetVisitorById
  InviteLinksTable --> GetInviteByToken
  VisitRequestsTable --> GetVisitReqByToken
  VisitRequestsTable --> GetVisitRequests

  GetInviteByToken --> API
  GetVisitReqByToken --> API
  GetVisitors --> API
  GetVisitorById --> API
  GetVisitRequests --> API
  PutInviteLink --> API
  PutVisitRequest --> API
  PutVisitor --> API

  API --> Browser

  %% Infra
  SAM --> CFN
  CFN --> API
  CFN --> Cognito
  CFN --> CloudFront
  CFN --> S3
  CFN --> DNS
  CFN --> InviteLinksTable
  CFN --> VisitorsTable
  CFN --> VisitRequestsTable
  CFN --> VerifiedPerm

  DeployBackend --> SAM
  DeployFrontend --> SAM
  CICD --> DeployBackend
  CICD --> DeployFrontend

  %% Click Events
  click S3 "https://github.com/elmarguevarra/visitor-management/blob/main/infrastructure/resources/s3-bucket-cloudfront.yaml"
  click CloudFront "https://github.com/elmarguevarra/visitor-management/blob/main/infrastructure/resources/s3-bucket-cloudfront.yaml"
  click DNS "https://github.com/elmarguevarra/visitor-management/blob/main/infrastructure/resources/hosted-zone.yaml"
  click DNS "https://github.com/elmarguevarra/visitor-management/blob/main/infrastructure/resources/record-set.yaml"
  click ACM "https://github.com/elmarguevarra/visitor-management/blob/main/infrastructure/resources/cognito-client-domain.yaml"
  click API "https://github.com/elmarguevarra/visitor-management/blob/main/infrastructure/resources/api-gateway-lambda.yaml"
  click AuthAuthorizer "https://github.com/elmarguevarra/visitor-management/blob/main/backend/src/handlers/auth/authorizer.mjs"
  click AuthVerifier "https://github.com/elmarguevarra/visitor-management/blob/main/backend/src/handlers/auth/jwtVerifier.mjs"
  click GetInviteByToken "https://github.com/elmarguevarra/visitor-management/blob/main/backend/src/handlers/get-invite-by-token.mjs"
  click GetVisitReqByToken "https://github.com/elmarguevarra/visitor-management/blob/main/backend/src/handlers/get-visit-request-by-token.mjs"
  click GetVisitRequests "https://github.com/elmarguevarra/visitor-management/blob/main/backend/src/handlers/get-visit-requests.mjs"
  click GetVisitorById "https://github.com/elmarguevarra/visitor-management/blob/main/backend/src/handlers/get-visitor-by-id.mjs"
  click GetVisitors "https://github.com/elmarguevarra/visitor-management/blob/main/backend/src/handlers/get-visitors.mjs"
  click PutInviteLink "https://github.com/elmarguevarra/visitor-management/blob/main/backend/src/handlers/put-invite-link.mjs"
  click PutVisitRequest "https://github.com/elmarguevarra/visitor-management/blob/main/backend/src/handlers/put-visit-request.mjs"
  click PutVisitor "https://github.com/elmarguevarra/visitor-management/blob/main/backend/src/handlers/put-visitor.mjs"
  click Utils "https://github.com/elmarguevarra/visitor-management/blob/main/backend/src/handlers/utils.mjs"
  click Cognito "https://github.com/elmarguevarra/visitor-management/blob/main/infrastructure/resources/cognito-user-pool.yaml"
  click GoogleIdP "https://github.com/elmarguevarra/visitor-management/blob/main/infrastructure/resources/google-identity-provider.yaml"
  click VerifiedPerm "https://github.com/elmarguevarra/visitor-management/blob/main/infrastructure/resources/verified-permissions.yaml"
  click VisitorsTable "https://github.com/elmarguevarra/visitor-management/blob/main/infrastructure/resources/dynamodb-stack.yaml"
  click InviteLinksTable "https://github.com/elmarguevarra/visitor-management/blob/main/infrastructure/resources/dynamodb-stack.yaml"
  click VisitRequestsTable "https://github.com/elmarguevarra/visitor-management/blob/main/infrastructure/resources/dynamodb-stack.yaml"
  click SAM "https://github.com/elmarguevarra/visitor-management/blob/main/template.yaml"
  click SAM "https://github.com/elmarguevarra/visitor-management/blob/main/samconfig.toml"
  click CFN "https://github.com/elmarguevarra/visitor-management/blob/main/infrastructure/resources/*.yaml"
  click DeployBackend "https://github.com/elmarguevarra/visitor-management/blob/main/scripts/deploy_backend_and_infra.sh"
  click DeployFrontend "https://github.com/elmarguevarra/visitor-management/blob/main/scripts/deploy_frontend.sh"
  click CICD "https://github.com/elmarguevarra/visitor-management/blob/main/.github/workflows/deploy.yml"

  %% Styles
  classDef presentation fill:#ADD8E6,stroke:#333,stroke-width:1px
  classDef compute fill:#FFA500,stroke:#333,stroke-width:1px
  classDef data fill:#90EE90,stroke:#333,stroke-width:1px
  classDef infra fill:#D3D3D3,stroke:#333,stroke-width:1px
```
