Povixa Docs
Povixa / Docs / v0.9.4 Latest
POVIXA ARCHITECTURE SPECIFICATION

Developer Documentation & SDK Guides

A single client SDK, 9 native subsystems, zero duct tape SaaS. Run on cloud or self-host 100% on your own metal.

Start

Quickstart in 60s

Integrate 1 unified SDK replacing 9 disparate tools. Configure environment variables and run.

View details
Sovereign

Self-Hosted Deployment

Run the entire stack (Core, PostgreSQL, ClickHouse & MinIO) with a single docker-compose.yml file.

View details
5 Languages

Polyglot SDK Reference

First-class type-safe client libraries for TypeScript, Go, Python, Flutter/Dart and Rust.

View details
Enterprise

Zero-Trust Security

Distributed token verification via ed25519 signatures, WebAuthn Passkeys and RBAC.

View details

1. Install Unified SDK

Select your preferred package manager to install the official typed client.

$ bun add @povixa/sdk

💡 Design note: You only need to import @povixa/sdk to interact with all 9 subsystems (Auth, Config, S3, Notify, Telemetry, etc.). No fragmented dependencies.

2. Initialize & Polyglot Client Usage

Real-world code specification with complete end-to-end type safety for each language.

povixa-client.ts
import { PovixaClient } from '@povixa/sdk';

// 1. Initialize client (auto-detects local docker or Povixa Cloud)
export const povixa = new PovixaClient({
  endpoint: process.env.POVIXA_ENDPOINT ?? 'http://localhost:8080',
  apiKey: process.env.POVIXA_API_KEY!
});

// 2. Auth & Session verification (sub-millisecond ed25519 validation)
const { user, session } = await povixa.auth.verifySession(authToken);

// 3. Realtime Feature Flag evaluation (<2ms edge cache hit)
const isNextEngine = await povixa.config.getBool('features.next_pipeline', {
  userId: user.id,
  tenantId: user.organizationId,
  fallback: false
});

// 4. S3 Object Storage with automatic presigned direct upload URL
const presigned = await povixa.storage.createPresignedUpload({
  bucket: 'datasets',
  key: `users/${user.id}/export-model.parquet`,
  expiresInSeconds: 900
});

3. Live Subsystem Inspector (Live Mock)

Click any subsystem to preview live JSON response payload and edge response latency.

LIVE MOCK EMULATOR
200 OK POST /v1/config/evaluate
Latency: Edge Cache • 1.2ms
{
  "flag_key": "features.next_pipeline",
  "value": true,
  "variant": "rollout_50",
  "reason": "PERCENTAGE_TARGETING_MATCH",
  "cache_hit": true,
  "evaluated_at": "2026-10-11T11:40:00Z",
  "environment": "production"
}

4. Self-Hosting with Docker Compose

Full data sovereignty. Run on personal VPS, Hetzner, AWS, or on-premise bare-metal cluster.

Gateway

Port :8080

gRPC Telemetry

Port :9090

Relational DB

PostgreSQL 16

OLAP Engine

ClickHouse Server

version: '3.8'

services:
  povixa-core:
    image: ghcr.io/povixa/core:latest
    container_name: povixa_engine
    restart: always
    ports:
      - "8080:8080" # Unified API Gateway & Management
      - "9090:9090" # High-speed Telemetry & gRPC
    environment:
      - POVIXA_MODE=standalone
      - DB_URL=postgres://povixa:secret@postgres:5432/povixa_db
      - CLICKHOUSE_URL=http://clickhouse:8123
      - S3_ENDPOINT=http://minio:9000
      - S3_ACCESS_KEY=povixa_admin
      - S3_SECRET_KEY=povixa_supersecret
      - JWT_PRIVATE_KEY=${POVIXA_ED25519_KEY}
    depends_on:
      - postgres
      - clickhouse
      - minio

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: povixa_db
      POSTGRES_USER: povixa
      POSTGRES_PASSWORD: secret
    volumes:
      - pgdata:/var/lib/postgresql/data

  clickhouse:
    image: clickhouse/clickhouse-server:latest
    volumes:
      - chdata:/var/lib/clickhouse

  minio:
    image: minio/minio:latest
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: povixa_admin
      MINIO_ROOT_PASSWORD: povixa_supersecret
    volumes:
      - miniodata:/data

volumes:
  pgdata:
  chdata:
  miniodata:

5. Architecture Topology & Flow Map

How a single Client SDK communicates through Edge Gateway to decoupled subsystems.

LAYER 1: CLIENT

Your Application

Web (Svelte/React/Vue), Mobile (Flutter/iOS), Backend Microservices.

import { Povixa } from '@povixa/sdk'
LAYER 2: EDGE GATEWAY

Povixa Core Router

ed25519 Token Verification, In-Memory Flag Caching (<2ms), Presign S3 URL Dispatcher.

Zero Network Round-trips
LAYER 3: STORAGE ENGINES

Sovereign Infrastructure

PostgreSQL (Metadata & Auth), ClickHouse (Telemetry), MinIO/S3 (Object Storage).

100% Data Sovereignty

Was this documentation helpful?

Share your feedback to help us refine the technical documentation.

Edit this page on GitHub Last updated: Today • Open Source MIT / AGPL-3.0

Ready to build with a unified platform?

Free forever for community and open source projects with Povixa badge. Zero credit card required.

Open Povixa Console Customer Support