Skip to content
SARC

Architecture overview

SARC is a three-layer composition that sits above the customer’s existing Kosli and ServiceNow deployments.

Three-layer model

Section titled “Three-layer model”
┌─────────────────────────────────────────────────────────────────┐
│ SARC                                                            │
│  - karc-portal (Next.js 16 standalone)                          │
│  - scripts/ci/* (orchestration: promote, kosli-score, sn-cr)    │
│  - Helm charts (apps/karc-portal/, apps/podtato-head/)          │
│  - Terraform stacks (infra/{aws,azure,gcp,k3d}/)                │
│  - ArgoCD ApplicationSets (gitops/applicationsets/)             │
└─────────────────────────────────────────────────────────────────┘
                              ▲ ▼
                  consumes      writes back
                              ▲ ▼
┌──────────────────────────┐ ┌──────────────────────────────────┐
│ Kosli                    │ │ ServiceNow                       │
│ - Attestations           │ │ - DevOps Change Velocity         │
│ - Trails (per pipeline)  │ │ - CAB workflow                   │
│ - Environment snapshots  │ │ - CMDB                           │
│                          │ │ - Incident / Problem records     │
└──────────────────────────┘ └──────────────────────────────────┘
                              ▲ ▼
┌─────────────────────────────────────────────────────────────────┐
│ Customer's runtime                                              │
│  - One of: AWS EKS / Azure AKS / GCP GKE / ROSA OpenShift / k3d │
│  - One of: GitLab CI / GitHub Actions / Azure DevOps / Jenkins  │
└─────────────────────────────────────────────────────────────────┘

What runs in the cluster

Section titled “What runs in the cluster”
karc-<env> namespace
├── karc-portal (Deployment, 2 replicas)
│   - Next.js standalone, non-root, readonly-fs
│   - Talks to: PostgreSQL, Redis, Kosli, ServiceNow, Cloud APIs
├── karc-portal-postgresql (StatefulSet, primary)
├── karc-portal-redis-master (StatefulSet)
├── karc-portal-github-mcp (Deployment, optional)
│   - github-mcp-server v1.0.4 sidecar
│   - HTTP Streamable transport on :8080/
├── karc-mcp (Deployment, 2 replicas)
│   - SARC's own MCP server (read tools)
├── podtato-head-* (Deployments, demo app)
│   - 6 microservices: entry, hat, left-arm, right-arm, left-leg, right-leg
├── CronJobs:
│   - karc-portal-aict-reconcile (AI Control Tower sync, 15-min)
│   - karc-portal-cache-warmup
│   - karc-portal-ssa-cleanup (server-side apply cleanup)
│   - kosli-reporter (env snapshots back to Kosli)
└── ArgoCD Applications:
    - karc-portal-<cloud>-<env>
    - podtato-head-<cloud>-<env>

Data flow per change

Section titled “Data flow per change”
  1. Developer pushes to a feature branch.
  2. CI (GitLab / GitHub / ADO) runs the compliance pipeline: SAST + SCA + container + secret + IaC scans.
  3. Kosli receives attestations for each scan stage. Trail is built per pipeline run.
  4. Pipeline calls scripts/ci/kosli-score.sh which computes the 5-axis risk score from the trail.
  5. Pipeline calls scripts/ci/servicenow-cr.sh which creates a ServiceNow Change Request with the risk score + release notes attached.
  6. Approval check on the ADO/GitLab environment waits for the ServiceNow CR to flip to approved. Low-risk CRs may auto-approve per the customer’s CAB policy.
  7. gitops:bump:karc-portal:dev updates envs/dev/image-tag.yaml on the gitops branch.
  8. ArgoCD detects the gitops branch change, runs PreSync hooks (Kosli assert + ServiceNow CR check), applies the new image to the cluster.
  9. kosli-reporter CronJob reports the new environment snapshot back to Kosli (closes the loop).
  10. karc-portal /timeline SSE stream lights up with every event in real time.

What the portal sees

Section titled “What the portal sees”

The karc-portal is the read surface over all of this:

  • / dashboard: per-environment release health, Kosli compliance state, pending CRs, vuln burndown
  • /compliance/*: per-framework cards, control mapping, evidence export
  • /change-requests: ServiceNow CR list with 5-axis risk tab + Kosli evidence chain
  • /timeline: real-time stream of every deploy/CR/Kosli/ArgoCD event
  • /services, /services/graph, /cmdb: service catalogue + dependency graph + ServiceNow CMDB browser
  • /vulnerabilities, /sbom, /security: aggregated finding view across all scanners
  • /audit: hash-chained audit log of every portal action
  • /admin/mcp: MCP-Client Gateway demo (Phase 1)

Full surface inventory in docs/PORTAL-FEATURES.md in the repo.

Multi-cloud and multi-CI

Section titled “Multi-cloud and multi-CI”