Documentation — Architecture

# Architecture Overview

TuneVault is split into two sides that never fully trust each other: the app (cloud or self-hosted) and an agent that runs on your Oracle server. The agent never listens for anything. It only ever calls out.

## The two sides

Everything in TuneVault falls into one of two domains. Getting this split right is the whole security model, so it's worth stating plainly before anything else:

Side | What lives here | Who initiates contact
--- | --- | ---
TuneVault | The web app (Node/Express), its Postgres database, the health-check engine, TuneOps, the AI layer. | Never reaches into your network — not even to advance an ADOP patch phase. Every control action, including the full ADOP lifecycle (validate through cutover and cleanup), is picked up by the agent on its own next outbound poll, never pushed to it.
Your network | The agent (`oracle-proxy.py`), your Oracle database, your EBS app tier. | The agent polls outbound on a schedule. Nothing is ever pushed in.

In the cloud deployment, "TuneVault" above is `tunevault.app`, running on Render, with its Postgres on Neon. In the self-hosted deployment, "TuneVault" is a container or systemd service running inside your own network — the app and its database both sit on your hardware, and the only outbound call that ever leaves is a periodic license check to `tunevault.app`.

Either way, the agent-to-app relationship is identical. Self-hosted doesn't change the protocol — it changes which side of the boundary the app itself lives on.

## Why outbound-only matters

A monitoring agent that needs an inbound port open is a firewall exception your security team has to approve, justify, and re-approve at every audit. An agent that only makes outbound HTTPS calls looks, from the firewall's point of view, identical to the server just browsing a website. Most networks already allow that by default.

This is the entire reason self-hosted TuneVault works inside networks that block everything else: the agent is always the one knocking. Nobody ever knocks on it.

## What actually crosses the boundary

Not "your data stays inside your network" as a slogan — the literal payloads, so you can verify it yourself:

→ Agent poll: the agent's API key and a request for queued commands. Response is either "nothing to do" or a command payload (e.g. "run this health check").
→ Command result: after the agent runs a check locally, it POSTs the result back — the finding data your health check produced, nothing more.
→ License validation (self-hosted only, once per boot): a license key and a hostname. That's the entire payload — no connection details, no query text, no findings.

What never crosses it: your Oracle username or password (encrypted at rest, decrypted only in memory on the app side, per connection, when a check actually runs), the SQL your database executes, or any AWR/ASH/session data beyond what a specific health check explicitly asked for and you explicitly ran.

## The layers, top to bottom

The rest of this documentation set covers each of these in depth. This is the map:

Layer | What it does
--- | ---
Identity & access | Google OAuth / magic link, session cookies, role-based access control, per-team permissions.
Credential security | AES-256-GCM encryption for stored Oracle/EBS/SSH passwords, decrypted only in memory, only on demand.
Connectivity & agent protocol | The outbound-poll mechanism described above — how a command reaches your server and how a result gets back.
Health check engine | 200+ checks, scoring, finding history and deduplication across repeated runs.
AI layer | TuneBot (RAG over Oracle documentation) and the DBA Agent (autonomous, read-only, tool-using).
Operational control plane | EBS and DB operations — starting/stopping services, running SQL ops, always mediated through the agent.
TuneOps & automation | Ticketing, autonomous scheduling, occurrence tracking across recurring findings.
Licensing & deployment | How cloud tiers and self-hosted license keys are issued, validated, and enforced.

Questions about a specific layer? See Oracle Privilege Model for exactly what database access TuneVault requests, or download self-hosted to run this architecture entirely on your own infrastructure.