Executive summary

Ouranos is a reusable SaaS template that provisions a complete, production-shaped product in one scripted run: a serverless AWS foundation (Terraform, Aurora DSQL, SES, Route 53, CloudFront with Lambda via OpenNext), a Next.js monorepo with three public surfaces (marketing landing, authenticated app, documentation), sign-in and organizations through Better Auth with optional Stripe billing, and a GitHub Actions pipeline that reaches the cloud through OIDC only — no stored keys. Hosting is pluggable behind one Terraform target interface: AWS-native is the reference; Vercel and Cloudflare are opt-in. The template repository is itself a live instance of the template, so every claim on this page is exercised by the thing that makes it.

What you getCopy Anchor Link

• Three hostnames per environment on your own zone Z: the landing at Z, the app at app.Z, these docs at docs.Z (dev under dev.Z; one ephemeral preview per pull request at pr-<n>.dev.Z). TLS, DNS and e-mail records are written by Terraform — nobody pastes a record by hand except the one NS delegation into a parent zone the account does not own.
• Two long-lived environments — dev converges on every merge to main; prod changes only through a semver release tag behind a GitHub environment gate. Each has its own Terraform state, its own CI role and its own database.
• A product, not a skeleton: email/password and Google sign-in, organizations with roles and invitations, an admin panel with a one-time bootstrap link, transactional e-mail through SES, and (when payments are on) Stripe checkout, customer portal and idempotent webhooks — all behind a single authorize(actor, action, resource) enforcement point.
• Guardrails that are mechanisms, not habits: secrets live only in SSM Parameter Store; the docs site publishes from a fail-closed allowlist; CI gates (lint, types, unit, integration, e2e on the preview, SAST, secret scan, IaC and dependency audit, blueprint drift) are required checks on main; every resource carries the project prefix and tag so teardown can prove emptiness.

System contextCopy Anchor Link

How an instance sits among the people and systems around it. The human speaks at Intake and Close-out; in between, an AI agent (or a developer) works through GitHub, and GitHub reaches the cloud account through short-lived OIDC roles.

C4Context
    title Ouranos instance — system context
    Person(owner, "Owner / operator", "Answers Intake, runs the make lifecycle, cuts releases")
    System_Ext(github, "GitHub", "Repository, rulesets, Actions — OIDC, no stored keys")
    System_Ext(agent, "AI agent", "Claude Code / Codex: opens PRs, merges green PRs")
    Person(user, "End user", "Browser: landing, app, docs")
    System_Boundary(account, "Cloud account of the instance") {
        System(ouranos, "Ouranos instance", "Z / app.Z / docs.Z on the chosen target; Aurora DSQL, SES, SSM")
    }
    System_Ext(google, "Google OAuth 2.0", "Sign-in")
    System_Ext(stripe, "Stripe", "Checkout, portal, webhooks (optional)")
    System_Ext(parent, "Parent DNS zone", "NS delegation only — off limits")
    BiRel(user, ouranos, "Uses; receives verification, reset and invite mail", "HTTPS / SES")
    Rel(owner, github, "Merges, tags v*")
    Rel(agent, github, "Pull requests")
    Rel(github, ouranos, "terraform plan / apply", "OIDC roles per environment")
    Rel(ouranos, google, "OAuth redirect and callback")
    Rel(ouranos, stripe, "Checkout; webhooks")
    Rel(parent, ouranos, "NS records")

How it is operatedCopy Anchor Link

Everything is a make target that reads the committed ouranos.config.json; there is no console step and no second configuration source.

The humans' remaining list is short and is printed at the end of make init: confirm the SNS budget-alert subscription, publish the Google consent screen, paste the NS delegation when the parent zone is outside the account, and supply Stripe live keys if payments go live.

Cost and operations in one paragraphCopy Anchor Link

An idle instance with both environments up costs about USD 5–6 per month with prod health checks on (about USD 1–2 with them off): the Route 53 zone and health checks are the only fixed items; Lambda, DSQL, SES and CloudFront scale to zero and previews exist only while a pull request is open. Each instance carries an AWS Budget with alerts at 50/80/100 % of a USD 50 guardrail plus cost-anomaly detection, and the deploy pipeline uses GitHub-hosted minutes only within the plan's included allowance. Operationally, deploys are Terraform applies of a content-hashed artifact (identical content is a no-op), rollback is the previous hash, and every destructive path ends in verify-empty.

ArchitectureCopy Anchor Link

The engineering blueprint lives in the repository under docs/architecture/ and is published on this site under Architecture when the instance sets publish_internal_docs: true (a generated project leaves it off and publishes only its product guides):

• overview.md — system context, containers and components (C4 views)
• environments.md — hostnames, DNS, lifecycle (init/up/down/nuke) and target switch
• flows.md and auth-design.md — request path, sign-in, organizations, payments
• ci-design.md — the pull-request gauntlet, dev and prod deploys, previews
• cost-model.md, scaling-knobs.md, inventory.md (generated) — what it costs, what to turn, what exists

Product guides for people using the app: Getting started, Organizations and Billing.