> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pcnaid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# KeylessSSL architecture overview

> The verified services, data model, authentication, configuration, and certificate operations of KeylessSSL.

# KeylessSSL architecture overview

## Repository structure

KeylessSSL is a pnpm workspace with three deployed applications and one shared UI package:

| Workspace | Path | Responsibility |
| - | - | - |
| `@keylessssl/marketing` | `apps/marketing/` | Public website with docs, security, status, changelog, and pricing sections. Vite build deployed as a Cloudflare Pages project. |
| `@keylessssl/portal` | `apps/portal/` | Authenticated React SPA for domains, certificates, API keys, webhooks, audit log, usage, and settings. Vite build deployed as a separate Cloudflare Pages project. |
| `@keylessssl/api` | `apps/api/` | Express + PostgreSQL API backing the portal and API key workflows. Runs as a containerized Node service. |
| `@keylessssl/ui` | `packages/ui/` | Shared copy and constants used by the frontend applications. |

The API entry point constructs the Express app, initializes observability, starts background workers, and listens on port 8080.

## Request and certificate flow

1. A signed-in user or scoped API key creates a domain.
2. The API stores the domain under the caller's organization and returns a unique ownership TXT record plus a delegated-validation CNAME.
3. Verification performs live TXT lookup for the organization-specific token. It also checks the CNAME and atomically claims the apex for one organization.
4. Issuance is allowed only for a verified domain whose apex is not claimed by another organization.
5. The certificate provider creates or reads a Cloudflare for SaaS Custom Hostname and maps Cloudflare hostname and SSL states to `active`, `pending`, or `error`.
6. Certificate and domain rows retain provider identifiers and status. The sync route refreshes those rows from Cloudflare.

Cloudflare-managed certificates normally do not expose PEM bundles or private keys through KeylessSSL. The bundle route returns content only if the database record contains a PEM bundle.

## Authentication and authorization

Production configuration requires the Auth0 backend-for-frontend integration. The browser begins Authorization Code with PKCE; the API exchanges the code, verifies the identity token, creates or finds the user and organization, and issues a 12-hour KeylessSSL session token.

The `/v1` API guard accepts either that session token or an active, unexpired KeylessSSL API key. API-key routes enforce scopes. State-changing resource routes allow interactive owners, admins, and operators, while read-only members remain read-only. Organization, billing, team, profile-security, and API-key administration routes require interactive-user roles as defined by their handlers.

## Data model

PostgreSQL migrations define these main groups:

* Identity and tenancy: `users`, `organizations`, and `organization_members`.
* Domain control: `domains` plus globally unique `apex_claims` for tenant-bound ownership.
* Certificates: `certificates`, including Cloudflare provider IDs, provider status, validation records, and optional stored bundle fields.
* Credentials and notifications: `api_keys`, `webhooks`, and `webhook_deliveries`.
* Traceability and workflow: `audit_events`, `clients`, `verification_links`, and `idempotency_keys`.
* Supporting operations: email verification and delivery tables, email suppression, billing columns, durable rate-limit counters, and schema migrations.

Every domain, certificate, API key, webhook, client, verification link, and audit event query in the primary routes is scoped by organization ID.

## Runtime configuration

The API needs a PostgreSQL database, session and API-key protection secrets, webhook signing secrets, Cloudflare for SaaS access, and Auth0 settings before it starts in production. The portal needs the API base URL and its OIDC client settings. Configuration is supplied by the deployment environment; no credential values or setting names are published here.

Other implemented configuration covers public URLs, CORS origins, DNS verification mode, rate limits, webhook retries, email delivery via Resend, Stripe billing, Sentry, and PostHog. Production forces live DNS verification even if a bypass value is configured.

Required production services: PostgreSQL, Auth0, Cloudflare zone `keylessssl.dev` with SaaS Custom Hostnames enabled, Stripe account with configured prices, Resend for transactional email, and stable public URLs for `keylessssl.dev`, `app.keylessssl.dev`, and `api.keylessssl.dev`.

## Billing and plan limits

KeylessSSL uses Stripe for subscription management with two plans:

| Plan | Price | Domain limit | Seat limit |
| - | - | - | - |
| Hacker | \$0/month | 3 | 1 |
| Pro | \$15/month | 100 | 10 |

Domain creation and team invites enforce plan limits at the API level. Rate limiting is per-client-IP (default 120 requests per minute across `/v1` routes) and is not tiered by plan.

## Certificate operations

Certificate operations call the Cloudflare API for the configured zone. No per-hostname origin, SNI, CA, bundle, or TLS extras are sent to Cloudflare.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.