ORO Platform Overview¶

ORO's entire technology platform runs on Google Cloud Platform across three fully isolated environments — development, staging, and production. Every component is defined as code, every deployment is automated and tracked, and every engineer operates on the same repeatable foundation. This page is the ten-minute read that gives a complete picture of what we've built and why it matters.

What We've Accomplished¶

100% infrastructure-as-code — no engineer has ever clicked "create" in the GCP console to provision a production resource. Every server, network rule, and database is version-controlled and reproducible.
GitOps delivery pipeline — merging code to the main branch triggers an automated pipeline that validates, tests, and deploys to the target environment. The full audit trail of every change lives in git.
Zero-trust security from day one — all service-to-service communication is encrypted and authenticated. No service can reach another unless explicitly permitted. Credentials are never hardcoded anywhere in the codebase.
Three production-parity environments — development mirrors staging mirrors production. Bugs caught in dev stay in dev.
Centralized observability — every service emits metrics, logs, and traces to a unified monitoring stack. The team sees a problem before users do.
Safe, automated database migrations — schema changes go through a three-stage validation pipeline including a real dry-run on a disposable database clone before touching production data.

The Five Layers¶

Layer 1 — Infrastructure & Provisioning¶

The Automated Foundation

Component	Technology	What it does
Cloud provider	Google Cloud Platform (GCP)	Hosts all compute, networking, storage, and managed services
Infrastructure-as-code	Terraform + Terragrunt	Defines every cloud resource as versioned configuration files
Networking	GCP VPC, Private Service Connect	Isolates each environment in its own private network; no public database endpoints

Every piece of infrastructure — Kubernetes clusters, databases, load balancers, DNS entries, firewall rules — is declared in code and applied through an automated pipeline. There are no snowflake servers. If an environment were destroyed, it could be recreated from scratch with a single command.

Layer 2 — Delivery & Operations¶

Deployment Velocity & Reliability

Component	Technology	What it does
CI/CD pipelines	Bitbucket Pipelines	Automates build, test, and deployment for every code change
GitOps deployments	ArgoCD	Watches the git repository and continuously syncs the running platform to the desired state
Metrics & dashboards	Prometheus + Grafana	Real-time visibility into CPU, memory, request rates, error rates, and latency across all services
Log aggregation	Loki	Centralized log storage and search — one place to debug any service

Code goes from a developer's laptop to production through a fully automated pipeline. Deployments are reversible — rolling back to a previous version is a one-click operation. The team doesn't deploy on Fridays because there's nothing to fear about Monday morning, not because deployments are risky.

Layer 3 — Data & Intelligence¶

The Proprietary Data Moat

Component	Technology	What it does
Relational database	Cloud SQL MySQL 8.0	Primary structured data store — each microservice owns its own isolated schema
Document database	MongoDB (Percona PSMDB Operator)	Flexible document storage for unstructured or semi-structured data, HA in staging/prod
Cache	Cloud Memorystore Redis	High-speed in-memory cache for session data and frequently accessed records
Event streaming	Apache Kafka	Asynchronous messaging between services — decouples producers from consumers
Schema migrations	Flyway (via `oro-database-migrations`)	Version-controlled, automated database schema changes with rollback support

Data is isolated by design. No microservice can read another service's database — all cross-service data sharing happens through APIs or Kafka events. Schema changes are never applied manually: they go through a three-stage automated pipeline (validation → dry-run on a clone → apply) so a bad migration can never silently corrupt production.

Kafka topics in production:

Topic	Purpose
`check-health-topic`	Service health events
`service-log-topic`	Service-level log events
`client-log-topic`	Client-level log events
`account-event-log-topic`	Account lifecycle events

Layer 4 — Service & Application¶

Modular Core Architecture

Component	Technology	What it does
Container orchestration	GKE (Google Kubernetes Engine)	Runs, scales, and heals containerized services automatically
Service mesh	Istio	Encrypts all service-to-service communication; enforces traffic policies at the network level
Core microservices	4 services	Identity, core business logic (monolith), communication, analytics — each independently deployable
API gateways	4 gateways	Separate entry points for different client types and partner integrations

The platform is built on a microservices architecture: four independently deployable services, each with its own database, deployment pipeline, and team ownership. Services communicate over an encrypted mesh (mutual TLS — both sides verify each other's identity before any data is exchanged). Adding a new service or scaling an existing one has zero impact on the others.

Service map:

                    ┌──────────────────────────────────────────┐
                    │            API Gateways (×4)             │
                    │  oro · orofi · communication · analytics  │
                    └──────────────┬───────────────────────────┘
                                   │  mTLS (encrypted, authenticated)
          ┌───────────────┬────────┴──────────┬──────────────────┐
          ▼               ▼                   ▼                  ▼
   microservice-    microservice-      microservice-      microservice-
     identity        monolith         communication        analytics
          │               │                   │                  │
          ▼               ▼                   ▼                  ▼
      MySQL DB        MySQL DB           MySQL DB           MySQL DB
                          │
                     MongoDB  ──  Redis  ──  Kafka

Layer 5 — Client & Interaction¶

The User-Facing Edge

Component	Technology	What it does
API gateways	4 Istio-backed gateways	Routes external traffic (web, mobile, partner APIs) to the correct internal service
TLS termination	Istio ingress gateway + cert-manager	Automatically provisions and renews SSL/TLS certificates for all public endpoints
DNS	GCP Cloud DNS	Manages all domain routing for `.dev.orofi.xyz`, `.stage.orofi.xyz`, `*.orofi.xyz`
DDoS & rate limiting	GCP Load Balancer	First line of defense before traffic enters the platform

All public traffic enters through one of four API gateways, each scoped to a different client type. No internal service is ever directly reachable from the internet. TLS certificates are provisioned and rotated automatically — the team has never manually renewed a certificate.

Security & Compliance¶

ORO operates a five-layer zero-trust security model. "Zero trust" means no component is trusted by default — every request must be authenticated and authorized, even between internal services.

Layer	What it protects	How
Network	Perimeter	Private VPCs per environment; no public database or internal service endpoints
Identity	Who can act	GCP Workload Identity — every service runs as a named service account with the minimum permissions needed
Transport	Data in motion	Istio mutual TLS — all service-to-service traffic is encrypted and both sides verify identity
Secrets	Credentials	GCP Secret Manager — zero hardcoded passwords or API keys anywhere in the codebase
Application	API access	JWT tokens + API keys validated at the gateway; OAuth2 Proxy for internal tooling

Additional controls:

Encryption at rest — the identity service encrypts sensitive data with Cloud KMS (Google's key management service) before writing to the database
Least-privilege access — engineers have read-only access to production by default; changes require explicit approval
Full audit trail — all infrastructure changes are tracked in git; GCP audit logs are retained for 400 days
Automated certificate rotation — TLS certificates for all public endpoints are renewed automatically via cert-manager

Compliance certifications

SOC 2 / ISO 27001 / GDPR certification status: [NEEDS TEAM INPUT]. The technical controls are in place — formal certification is a process decision.

Cost & Efficiency¶

Cost visibility: KubeCost (a Kubernetes cost monitoring tool) breaks down GCP spending per service, per namespace, and per environment — giving the team a clear view of what each part of the platform costs and where to optimize.

Built-in cost controls:

Mechanism	Savings
Dev environment auto-shutdown	Dev cluster scales to zero outside working hours — no idle spend
Staging at reduced tiers	Staging mirrors production architecture but at lower resource tiers
Committed Use Discounts (available)	30–55% savings on compute for predictable workloads
Spot/preemptible nodes (available)	Up to 80% savings on non-critical workloads

Spend figures

Actual monthly GCP spend by environment: [NEEDS TEAM INPUT — provide figures from GCP billing console or KubeCost export].

Key Numbers at a Glance¶

What	Value
Cloud provider	Google Cloud Platform
Environments	3 — dev, staging, production
Core microservices	4
API gateways	4
Relational databases	4 isolated MySQL schemas (Cloud SQL 8.0)
Document database	MongoDB (Percona, HA in prod/staging)
Cache	Cloud Memorystore Redis
Event streaming	Apache Kafka (4 topics)
Deployment model	GitOps via ArgoCD
IaC coverage	100% — Terraform + Terragrunt
Secrets management	GCP Secret Manager — zero hardcoded credentials
Observability	Prometheus + Grafana + Loki
Database migration safety	3-stage automated pipeline (validate → dry-run clone → apply)
TLS certificates	Automatically provisioned and renewed
Audit log retention	400 days (GCP Cloud Audit Logs)

Architecture at a Glance¶

graph TB
    Internet["🌐 Internet (Web / Mobile / Partners)"]

    subgraph Edge["Layer 5 — Edge"]
        GW["API Gateways ×4\n(Istio Ingress + TLS)"]
    end

    subgraph Services["Layer 4 — Services (GKE + Istio mTLS)"]
        ID["microservice-identity"]
        MN["microservice-monolith"]
        CM["microservice-communication"]
        AN["microservice-analytics"]
    end

    subgraph Data["Layer 3 — Data"]
        SQL["Cloud SQL MySQL\n(4 isolated schemas)"]
        MDB["MongoDB\n(Percona HA)"]
        RDS["Redis Cache"]
        KFK["Kafka\n(Event Streaming)"]
    end

    subgraph Infra["Layer 1 — Infrastructure (GCP + Terraform)"]
        GKE["GKE Kubernetes Cluster"]
        VPC["Private VPC Network"]
    end

    Internet --> GW
    GW --> ID & MN & CM & AN
    ID --> SQL
    MN --> SQL & MDB & RDS & KFK
    CM --> SQL & KFK
    AN --> SQL

Topic	Link
Detailed system architecture	System Overview
Architecture decisions and why	Architecture Overview
Full security controls	Security Model
All services and their owners	Service Catalog
Cost breakdown and optimization	Cost Overview
Compliance control inventory	Compliance
Database migration process	Database Migrations