INFRASTRUCTURE ARCHITECTURE

VietGara — Multi-Tenant SaaS Platform for Auto Garage Management & Maintenance

Version 1.2 — October 9, 2026 · Cloud: Google Cloud Platform (GCP) · Backend: Go

1. Introduction

This document describes VietGara’s physical/logical infrastructure on Google Cloud Platform (ADR-002), covering networking, compute, data, and how it is managed via Infrastructure as Code.

2. Overall Infrastructure Diagram

flowchart TB
  inet((Internet)) --> lb["Cloud Load Balancing + Cloud Armor (WAF/DDoS)"]
  lb --> cdn["Cloud CDN<br/>Owner Web and Admin Web static assets"]
  lb --> gke
  subgraph vpc["VPC vietgara-vpc (asia-southeast1)"]
    subgraph gkesub["gke-subnet"]
      gke["GKE Autopilot vietgara-prod<br/>gateway, core-services, finance-services, support-services, bff"]
    end
    subgraph datasub["data-subnet (private IP)"]
      sql[("Cloud SQL PostgreSQL<br/>regional HA")]
      redis[("Memorystore Redis")]
      kafka[("Managed Kafka")]
    end
    run["Cloud Run<br/>small webhook edge handlers (later)"]
  end
  gke --> sql & redis & kafka
  gke --> gcs[("Cloud Storage")]
  gke --> sm["Secret Manager"]
  gke --> mj["Mailjet API"]
  gke --> google["Google OAuth"]

3. List of GCP Infrastructure Components

Component	GCP Service	Role
Compute	GKE Autopilot	Runs all Go microservices, autoscales based on pod requests (ADR-009)
Relational database	Cloud SQL for PostgreSQL (regional HA)	One database for the modular monolith, one per split service later; multi-tenant RLS through the `vietgara_app` role (ADR-005, ADR-008)
Cache	Memorystore for Redis	Refresh-token sessions, OTPs, entitlement cache, daily transaction counters
Message broker	Google Cloud Managed Service for Apache Kafka (or Confluent Cloud)	Domain events via the outbox; topics per bounded context with DLQs (ADR-004)
Object storage	Cloud Storage	Garage logos, PDFs, invoices, repair photos
Identity	In-house Identity module + Google OAuth client	E-mail/password with e-mail OTP, Google sign-in (ADR-007)
Transactional e-mail	Mailjet (external SaaS)	OTP, invitation and notification e-mails (ADR-011)
API Gateway	Kong (on GKE) + Cloud Load Balancing	Single entry point, TLS termination
CDN	Cloud CDN	Distributes Owner Web and Admin Web static assets
WAF/DDoS	Cloud Armor	Blocks OWASP Top 10, DDoS at the edge
Secrets	Secret Manager	JWT signing key, database passwords, Mailjet and Google credentials, partner API keys/certificates
CI/CD	GitHub Actions + Artifact Registry + ArgoCD	Automated build, test, scan, and deploy (see Deployment Architecture)
IaC	Terraform (Release 9.2)	Manages all infrastructure as code
Observability	Cloud Logging (structured slog output); the backend is instrumented with OpenTelemetry as of Release 1.5 and exports via OTLP once a collector is configured — Cloud Trace/Cloud Monitoring as that collector is still infrastructure work, not yet provisioned	Metrics, centralized logging, distributed tracing

4. Region/Zone Strategy

Primary region: asia-southeast1 (Singapore) — the lowest latency to Vietnamese users among currently available GCP regions.
GKE Autopilot and Cloud SQL are configured as regional (multi-zone within the same region) to tolerate a single zone failure without service interruption, meeting NFR-AV-01 (99.5–99.9% uptime).
A multi-region contingency plan is only pursued if a higher SLA is required by a large enterprise customer — not yet necessary at the 100–1,000 garage scale.

5. Infrastructure as Code with Terraform

terraform/
  modules/
    vpc/              # VPC, subnet, firewall rules
    gke/               # GKE Autopilot cluster, namespaces
    cloudsql/          # Cloud SQL instance, database, private IP
    kafka/              # Managed Kafka cluster, topics (+ .dlq), ACLs
    memorystore/        # Redis instance
    storage/            # Buckets (logos, documents), IAM
    secrets/            # Secret Manager entries (actual values injected via CI, never committed)
  environments/
    dev/main.tf
    staging/main.tf
    production/main.tf

The state file is stored on a Cloud Storage backend with state locking, never stored locally.
Every infrastructure change goes through a Pull Request and terraform plan review before being applied (no manual applies from a personal machine against staging/production).

6. Backup & Disaster Recovery (see NFRD, Section 10)

Component	Backup Mechanism	Target RPO/RTO
Cloud SQL	Automated daily backups + Point-in-Time Recovery (transaction log)	RPO 15 minutes / RTO 4 hours
Cloud Storage	Versioning enabled + a lifecycle policy moving to colder storage tiers by file age	RPO near 0 (durable, multi-zone storage by default)
Infrastructure config (Terraform state, Helm charts)	Stored in Git + a versioned Cloud Storage backend	The entire infrastructure can be rebuilt from code within a few hours

Disaster recovery drills (restoring from backup, rebuilding the cluster from Terraform) are conducted at least twice a year per NFR-BR-04.

7. Conceptual Cost Considerations (Order of Magnitude)

Actual costs depend on real usage and require a separate detailed estimate (out of scope for this architecture document), but the main cost drivers to monitor as the tenant base grows include:

GKE Autopilot: billed by pod request (CPU/memory) — grows linearly with the number of services and replicas, not with a fixed node count.
Cloud SQL: instance cost (regional HA is more expensive than single-zone) plus storage that grows with accumulated data (especially transaction/audit logs).
Managed Kafka: billed by cluster capacity (vCPU, memory, storage) rather than per message — sized for retention and partition count; the dominant fixed cost at low volume.
Mailjet: billed by monthly e-mail volume (OTP and notification e-mails).
Egress traffic & CDN: grows with the volume of repair photos (Technician App) and downloaded PDFs/invoices.