Architecture Overview

ArkOS is a Platform-on-Kubernetes — a config-driven SaaS platform where product definitions, commercialization, and infrastructure are all declarative.

High-Level Architecture

┌─────────────────────────────────────────────────────────────┐
│                        ArkOS Platform                        │
│                                                             │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │ Identity │  │  Tenant  │  │  Subscr. │  │Entitlemnt│  │
│  │ Service  │  │ Service  │  │  Service │  │ Service  │  │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐  │
│  │               API Gateway (Fastify)                   │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐  │
│  │        meta/ YAMLs  →  arkgen  →  contracts          │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Key Components

meta/ — Source of Truth

All platform definitions live in meta/ as YAML files. This is the single source of truth for entities, modules, bundles, plans, and events. No hardcoded business logic — everything is declarative.

arkgen — Code Generator

arkgen reads meta/ YAMLs and generates:

• TypeScript contracts (@arkos/contracts)
• Connector packages for cross-service communication
• Documentation for this portal (in apps/developer-portal/docs/reference/)

Run pnpm generate to regenerate all artifacts.

Services — 28 Microservices

Each service follows a 4-layer architecture:

Layer	Responsibility
domain/	Entities (immutable), value objects, errors, use case interfaces
data/	Use case implementations, repository protocols
application/	HTTP controllers, event handlers
platform/	Infrastructure: PostgreSQL repos, connector adapters

Connector Pattern

Services never call each other over HTTP directly. Instead, they use typed connector packages:

import { ArkSubscriptionConnector } from '@arkos/connector-ark-subscription'
// Compile-time typed, no raw HTTP calls

Data Flow

User Request
    │
    ▼
API Gateway (auth, rate limit, tenant context)
    │
    ▼
Service (domain logic via use cases)
    │
    ├─► PostgreSQL (persistence)
    ├─► Redis (caching)
    └─► NATS JetStream (events)

Infrastructure

ArkOS runs on Kubernetes. Infrastructure definitions live in the infra/ repo:

• Kubernetes manifests per service
• Helm charts for deployment
• CI/CD pipelines (GitHub Actions)

For detailed architecture documentation, see the meta/docs/architecture/ directory in the monorepo root.