Core Services Overview

The eight core services form the foundation of the UNVRSL framework. core.console acts as the unified management plane and API gateway; the remaining services provide specialized functionality.

core.console

Unified management plane and API gateway for the UNVRSL ecosystem. core.console is the single entry point for all client interactions — project management, API key generation, service routing, quota enforcement, and usage tracking. Instead of connecting to each core service independently, clients authenticate through core.console and route all requests through it.

What It Does

• Dev user profiles — every core.auth user can become a dev user by accessing core.console for the first time. The dev profile (username, avatar) is separate from the auth identity and lives in the console database.


• Organizations — group multiple dev users under shared project ownership. Members have roles (admin, member, viewer) with fine-grained, project-level permission scoping controlled by admins.


• Project management — create and manage projects, each with its own set of enabled services. Projects belong to either a dev user or an organization. One-way transfer from dev user to org.


• API key generation — multiple scoped keys per project, controlling which services and how much usage is allowed. Keys are shown once at creation; only prefixes are stored.


• Request routing — validates API keys, checks project status, checks service permissions, enforces quotas, and routes requests to the appropriate internal core service.


• Billing — billing profiles attached to the owner (dev user or org), not to individual projects. Projects link to one billing profile. On transfer, billing is reassigned.


• Stats & logs — separate tables for granular request logs (error-focused, per-request) and precomputed stats (hourly rollups, dashboards). Pooled views at owner level.


• Project security — IP/domain whitelisting per project or per service. Deny-by-default: projects are locked until the developer adds security rules.


• Unified auth — SSO for the entire platform. One login through core.console grants access to all enabled services.

Architecture

core.console follows the three-layer model used by Google Cloud:

1. Console — management UI/API (dev user onboarding, org management, project creation, key management, stats dashboards, billing)


2. API Gateway — runtime entry point (key validation, quota enforcement, routing, logging)


3. Backend services — the other core services (auth, storage, ai, etc.) that do the actual work

→ Console Architecture · L4 code reference coming soon

core.auth

Centralized identity provider for the UNVRSL ecosystem. core.auth is the single source of truth for user identity, authentication, and session management. It operates as a standalone service on its own subdomain (core.auth.medkronos.com) and serves as the trust anchor for every application in the framework.

What It Does

• Master accounts — all user identity data (email, password, 2FA, profile) lives in core.auth. Apps never store credentials or personal data.


• JWT + session cookie — HMAC-signed (HS256) access tokens (15 min TTL) verified locally by apps without hitting core.auth. A session_ref HttpOnly cookie (30 days) is checked against the sessions table only at refresh. No refresh tokens, no rotation — revocation is a single session-row delete.


• Scoped permissions — three-tier scope model: simple (always allowed), advanced (blacklist check), critical (requires 2FA re-verification). Each app gets only the scopes it needs.


• Credit-based quotas — four resource quotas per account: storage (MB), AI credits, hypermedia credits, and special general credits (universal overflow pool). AI operations are measured in credits, not calls — input tokens, output tokens, and cached tokens have different costs. Users who exhaust a primary quota can borrow from special credits, letting them self-allocate resources based on their actual usage patterns.


• Cross-app SSO — one login, all apps. A single authentication at core.auth grants access to every app the user has been granted. Session carries across app switches with no re-auth.


• Federated UI — login, registration, and sensitive account operations (password change, 2FA setup) are served from core.auth's frontend, not shipped to apps. Apps embed or redirect to core.auth for these flows.


• Global account management — a self-service dashboard at core.auth.medkronos.com where users manage their account: change password/email, configure 2FA, bind social logins (Google, Apple), view/revoke app access, see active sessions.


• User Circle — a persistent UI element embedded in every UNVRSL app (inspired by Google's profile circle). Shows the user's avatar in a small circle; clicking it opens a quick-settings popover with the current account, account switching (if multiple accounts are logged in), quota usage (storage, AI tokens, hypermedia), and a log-out option. Owned by core.auth (its frontend holds the session context) and delivered to apps through core.console — apps never talk to microservices directly. Avatar images are user content stored in S3 via core.storage — apps don't need to build it.

How Apps Integrate

Each project in core.console has an app-facing identity. When a user visits an app without a session, the app redirects the user's browser to core.auth.medkronos.com for login (federated UI). core.auth handles authentication and redirects back with an authorization code. The app's backend exchanges that code at core.console (POST /v1/auth/token with its project API key), which relays to core.auth. The returned JWT is verified locally by the app (HMAC signature, no network call). All subsequent service calls — token refresh, file uploads, AI interactions — go through core.console exclusively.

User visits app → no session → redirect to core.auth (browser → federated UI)

    → user authenticates (password + 2FA)

    → core.auth redirects back with auth code

    → app backend POSTs to core.console /v1/auth/token (project API key)

    → core.console relays to core.auth → returns JWT + session_ref cookie

    → app verifies JWT locally (HMAC) → creates local linked_user record

    → app sets its own session

> Apps never call core.auth directly for service operations. Only the user's browser interacts with core.auth for federated UI pages (login, registration, authorize consent, account dashboard). All backend calls — code exchange, refresh, logout, profile reads, quota checks — go through core.console.medkronos.com/v1/auth/* with the project's API key in the Authorization header. core.console handles key validation, security rules, logging, billing — the single entry point for all project traffic.

Architecture & Docs

→ Auth Architecture — account model, session mechanics, token flow, database schemas
→ Registration — email/password, Google/Apple OAuth bindings (planned)
→ 2FA & Passkeys — TOTP, WebAuthn, recovery codes (planned)
→ Frontend — login popup, account management, global dashboard (planned)
→ Code Reference

core.storage

S3 storage, file tracking, and object management. Provides a unified API for uploading, downloading, and tracking files across all apps. Storage quotas are enforced per master account.

What It Does

• Pool management — dev users create storage pools via core.console. Each pool maps to an S3 bucket on a specific provider/region. Actual bucket names are auto-generated and never shown to users.


• Provider abstraction — S3 providers (AWS, Backblaze, MinIO, etc.) are configured via env vars or config files, not in the database. core.storage exposes a provider catalog to core.console for the pool creation UI.


• Sharding — files larger than the provider's single-PUT limit are automatically split into shards. Each shard is a separate S3 object. Upload/download is transparent to the client.


• Ownership & access control — every object has an ownership record with access level (viewer/editor/owner). Ownership uses soft revoke (expired_at) — revoking access preserves the audit trail.


• Soft delete — no user action permanently deletes data. Deleted objects get deleted_at set and are hidden from queries. A background cleanup job handles actual S3 removal after a configurable retention period.


• Comments — threaded comments on files with optional positional anchors (page, coordinates, timestamp).

Architecture

• Providers are config (env vars / JSON file), never in the database


• Pools are tied to core.console projects — one project can have multiple pools across providers/regions


• core.console provisions pools by calling core.storage's API — core.storage creates the actual S3 bucket using its stored credentials


• Quotas enforced at upload time via core.auth

→ Storage Architecture · Code Reference

core.ai

LLM abstraction layer and conversation platform. Provides a unified API for interacting with multiple LLM providers (OpenAI, Anthropic, Google) through provider adapters. Manages conversations, messages, media, cost tracking, and prompt management.

What It Does

• Provider abstraction — one internal message format, provider adapters translate in/out. Switch providers without changing app code. Streaming supported across all providers.


• Conversations & messages — persistent conversation threads with per-message model selection. Users can switch models mid-conversation (with cache break warning).


• Cost tracking — per-turn cost tracking (tokens, dollar cost, credit cost) with running cumulative totals. Integrated with core.auth quota enforcement — turns abort if quota exceeded.


• Media pipeline — file uploads via core.storage, compression/conversion via core.hypermedia. Users can't send messages until attached media is processed.


• System prompts — filesystem-based templates indexed in a database table. Developer-facing.


• Presets — user-facing conversation templates (like Gemini Gems or Perplexity Spaces) with avatars, descriptions, pre-prompts, and prompt templates.


• Skills — developer-facing configurations combining system prompts with model settings.


• Streaming — real-time SSE streaming from provider to client, normalized across providers.

Architecture

• Providers configured via env/config file (platform-owned keys, no BYOK)


• Conversations belong to app users (via core.auth user_id)


• Accessed via core.console (API gateway), calls core.auth, core.storage, core.hypermedia directly

→ AI Integration Architecture · Code Reference

core.assets

Public CDN for static reusable content. A filesystem-based asset router serving versioned branding, iconography, typography, design tokens, and frontend logic. Supports latest/stable/exact version resolution (pinned via info.md) with ETag caching.

Not tied to core.console — no API keys, no project scoping; projects (and anyone else) request resources directly with anonymous access (CORS *). User data is never served here: avatars and uploads live in S3 via core.storage.

→ Architecture · Code Reference

core.hypermedia

Media and document processing engine. Handles conversion, compression, and enhancement of media and document files. Used by apps that accept user uploads (PDFs, images, audio) for normalization and optimization.

→ Architecture · Code Reference

core.docs

Living documentation hub. This site. Serves as the single source of truth for architecture, conventions, setup guides, and module usage. Begins as structured Markdown, will evolve into a rendered documentation website powered by the same core services it describes.

→ Scope · Architecture

core.backend

Client SDK for the UNVRSL platform. A Composer package that applications install to interact with core.console. Provides PHP helpers for API key management, request signing, service calls, and shared utilities (DocumentShell, datetime parsing). Installed via Composer from the private GitHub repo.

→ Code Reference