# engineering

## Docs

- [Resource permissions](https://engineering.unkey.com/architecture/authorization/resource-permissions.md): Authorization permissions built from Unkey Resource Names
- [WorkOS permissions](https://engineering.unkey.com/architecture/authorization/workos-permissions.md): How WorkOS permission strings map to Unkey resource permissions
- [Architecture](https://engineering.unkey.com/architecture/index.md): System architecture and design references
- [Consistency model](https://engineering.unkey.com/architecture/ratelimiting/consistency-model.md): How rate limit state converges across processes and regions
- [Global counters](https://engineering.unkey.com/architecture/ratelimiting/global-counters.md): How G-Counters power cross-region rate limit convergence
- [Rate limiting](https://engineering.unkey.com/architecture/ratelimiting/overview.md): Architecture overview for Unkey's distributed rate limiter
- [Request path](https://engineering.unkey.com/architecture/ratelimiting/request-path.md): How one rate limit request is evaluated
- [Unkey Resource Names](https://engineering.unkey.com/architecture/resources/unkey-resource-names.md): Canonical resource names for public Unkey resources
- [0000 Template](https://engineering.unkey.com/architecture/rfcs/0000-template.md): You may copy this as a starting point, but it's not required
- [0001 RBAC](https://engineering.unkey.com/architecture/rfcs/0001-rbac.md)
- [0002 Secret Scanning](https://engineering.unkey.com/architecture/rfcs/0002-github-secret-scanning.md)
- [0003 Sentinel Pools](https://engineering.unkey.com/architecture/rfcs/0003-key-shape.md)
- [0004 COSS Starter](https://engineering.unkey.com/architecture/rfcs/0004-coss-starter.md)
- [0005 Analytics API](https://engineering.unkey.com/architecture/rfcs/0005-analytics-api.md): Unkey exposes APIs to retrieve all required data to build end-user facing dashboards and drive our customer's usage-based billing.
- [0006 Auth Migration](https://engineering.unkey.com/architecture/rfcs/0006-auth-migration.md): Migrate everything to WorkOS, despite their bad APIs..
- [0007 Client-side file structure](https://engineering.unkey.com/architecture/rfcs/0007-client-file-structure.md): File structure for our client apps
- [0008 Dataplane](https://engineering.unkey.com/architecture/rfcs/0008-dataplane.md): Global Unkey Deployment Architecture
- [0009 Pricing refresh for 2025](https://engineering.unkey.com/architecture/rfcs/0009-pricing-updates.md): We need to update our pricing for 2025
- [0010 Splitting the monorepo](https://engineering.unkey.com/architecture/rfcs/0010-split-monos.md): Splitting the monorepo into multiple smaller, more focused repositories / monorepos.
- [0008 URNs](https://engineering.unkey.com/architecture/rfcs/0011-unkey-resource-names.md): Implementing Uniform Resource Names (URNs) and Structured Error Codes at Unkey
- [0012 Stricter Linter](https://engineering.unkey.com/architecture/rfcs/0012-stricter-linter.md): Adding more strict lint rules to minimize issues in our codebase.
- [0013 TLS Certificates for custom domains](https://engineering.unkey.com/architecture/rfcs/0013-custom-domains.md): Issuing certificates for custom domains using Let's Encrypt's HTTP-01 challenge.
- [0014 Sentinel Middleware](https://engineering.unkey.com/architecture/rfcs/0014-sentinel-middleware.md): Composable HTTP middleware schema for Sentinel, Unkey's reverse proxy.
- [0015 Ratelimit Cross-Region Counts](https://engineering.unkey.com/architecture/rfcs/0015-ratelimit-cross-region-counts.md): Replace the ratelimit_blocklist propagation table with a G-Counter style sharing of actual per-region counts, eliminating the over-block failure modes of the current scheme.
- [0016 Vault S3 Storage](https://engineering.unkey.com/architecture/rfcs/0016-vault-s3-storage.md): Move vault object storage from a single R2 bucket to active-passive S3 buckets with cross-region replication and manual failover.
- [Authentication](https://engineering.unkey.com/architecture/services/api/api-design/auth.md): API authentication concepts, principals, and permission checks
- [Error handling](https://engineering.unkey.com/architecture/services/api/api-design/errors.md): Understanding and working with API errors
- [API design overview](https://engineering.unkey.com/architecture/services/api/api-design/index.md): Design philosophy for Unkey APIs
- [RPC-style API](https://engineering.unkey.com/architecture/services/api/api-design/rpc.md): Action-oriented API design
- [Configuration](https://engineering.unkey.com/architecture/services/api/configuration.md): Configuration model and required settings for the api service
- [Architecture](https://engineering.unkey.com/architecture/services/api/overview.md): API service components, request flow, and dependencies
- [Architecture](https://engineering.unkey.com/architecture/services/control-plane/api/architecture.md): Runtime composition and request flow for the control plane API
- [Configuration](https://engineering.unkey.com/architecture/services/control-plane/api/configuration.md): Configuration model and required settings for the control plane API
- [Overview](https://engineering.unkey.com/architecture/services/control-plane/api/overview.md): Control plane API for deployment intent and orchestration
- [Configuration](https://engineering.unkey.com/architecture/services/control-plane/worker/configuration.md): Configuration model and required settings for the control plane worker
- [Deployment sync](https://engineering.unkey.com/architecture/services/control-plane/worker/deployment-sync.md): How the control plane streams state changes to krane agents
- [Overview](https://engineering.unkey.com/architecture/services/control-plane/worker/overview.md): Control plane worker for workflow execution
- [Certificates](https://engineering.unkey.com/architecture/services/control-plane/worker/workflows/certificates.md): ACME challenge and certificate issuance
- [Custom domains](https://engineering.unkey.com/architecture/services/control-plane/worker/workflows/custom-domains.md): Custom domain verification and lifecycle
- [Deploy Billing](https://engineering.unkey.com/architecture/services/control-plane/worker/workflows/deploy-billing.md): How Deploy usage flows from ClickHouse to Stripe: the hourly month-to-date push and the month-end invoice close.
- [Deploy Spend Cap](https://engineering.unkey.com/architecture/services/control-plane/worker/workflows/deploy-spend-cap.md): How Compute spend budgets are checked, alerted, and enforced.
- [Deployments](https://engineering.unkey.com/architecture/services/control-plane/worker/workflows/deployments.md): Deploy, promote, rollback, cancel, and build-queue workflows
- [GitHub App](https://engineering.unkey.com/architecture/services/control-plane/worker/workflows/github-app.md): GitHub App authentication and failure modes
- [Key Last Used Sync](https://engineering.unkey.com/architecture/services/control-plane/worker/workflows/key-last-used-sync.md): How lastUsedAt timestamps flow from ClickHouse to MySQL.
- [Routing](https://engineering.unkey.com/architecture/services/control-plane/worker/workflows/routing.md): Frontline route assignment and traffic switching
- [Configuration](https://engineering.unkey.com/architecture/services/frontline/configuration.md): Configuration model and required settings for the frontline service
- [Failure modes](https://engineering.unkey.com/architecture/services/frontline/failure-modes.md): Failure scenarios, responses, and diagnosis
- [Frontline ingress](https://engineering.unkey.com/architecture/services/frontline/ingress.md): How Frontline terminates TLS, resolves hostnames, and proxies to deployment instances
- [Overview](https://engineering.unkey.com/architecture/services/frontline/overview.md): Multi-tenant ingress and gateway: TLS termination, policy enforcement, and routing to deployment instances
- [Firewall](https://engineering.unkey.com/architecture/services/frontline/policies/firewall.md): Policy that denies matched requests
- [Policies](https://engineering.unkey.com/architecture/services/frontline/policies/index.md): Policy engine and evaluation model
- [JWTAuth](https://engineering.unkey.com/architecture/services/frontline/policies/jwtauth.md): JWT authentication policy (schema only)
- [KeyAuth](https://engineering.unkey.com/architecture/services/frontline/policies/keyauth.md): API key authentication policy
- [Match expressions](https://engineering.unkey.com/architecture/services/frontline/policies/match-expressions.md): Request matching rules for policies
- [OpenAPI validation](https://engineering.unkey.com/architecture/services/frontline/policies/openapi.md): OpenAPI request validation
- [Policy schema](https://engineering.unkey.com/architecture/services/frontline/policies/policy.md): The frontline.v1.Policy message structure
- [Principal](https://engineering.unkey.com/architecture/services/frontline/policies/principal.md): Authenticated identity from auth policies
- [RateLimit](https://engineering.unkey.com/architecture/services/frontline/policies/ratelimit.md): Gateway rate limiting policy
- [Request flow](https://engineering.unkey.com/architecture/services/frontline/request-flow.md): Request lifecycle through Frontline, from TLS termination to the proxied response
- [Routing and failover](https://engineering.unkey.com/architecture/services/frontline/routing.md): Frontline routing decisions and cross-region forwarding
- [Configuration](https://engineering.unkey.com/architecture/services/krane/configuration.md): Configuration model and required settings for the krane service
- [Deployment](https://engineering.unkey.com/architecture/services/krane/deployment.md): Deployment model and failover expectations for the krane service
- [Overview](https://engineering.unkey.com/architecture/services/krane/overview.md): Kubernetes control agent for deployments and secrets
- [Secrets service](https://engineering.unkey.com/architecture/services/krane/secrets.md): Secrets decryption RPC and authentication
- [Authentication](https://engineering.unkey.com/architecture/services/vault/auth.md): RPC authentication and bearer token handling
- [Configuration](https://engineering.unkey.com/architecture/services/vault/configuration.md): Configuration model and required settings for the vault service
- [Overview](https://engineering.unkey.com/architecture/services/vault/overview.md): Encryption key service backed by object storage
- [Overview](https://engineering.unkey.com/company/index.md): How Unkey works
- [Meetings](https://engineering.unkey.com/company/meetings.md): Fight for your time and the time of others
- [Internal workflow](https://engineering.unkey.com/contributing/how-to-contribute.md): Internal guidelines for working in the Unkey repository
- [Local development](https://engineering.unkey.com/contributing/local/development.md): Set up, run, and test Unkey locally
- [Code quality](https://engineering.unkey.com/contributing/quality/code-quality.md): Design goals and coding standards for Unkey
- [Documentation](https://engineering.unkey.com/contributing/quality/documentation.md): Standards for internal documentation and code comments
- [Screenshots and recordings](https://engineering.unkey.com/contributing/quality/screenshots-and-recordings.md): How to capture screenshots and screen recordings for pull requests with visual changes
- [Anti-patterns](https://engineering.unkey.com/contributing/quality/testing/anti-patterns.md): Common testing mistakes to avoid
- [Fuzz tests](https://engineering.unkey.com/contributing/quality/testing/fuzz-tests.md): Finding edge cases with randomized inputs
- [HTTP handler tests](https://engineering.unkey.com/contributing/quality/testing/http-handler-tests.md): Testing API endpoints with the test harness
- [Testing](https://engineering.unkey.com/contributing/quality/testing/index.md): Testing standards and patterns for Unkey
- [Integration tests](https://engineering.unkey.com/contributing/quality/testing/integration-tests.md): Testing components with real dependencies
- [Simulation tests](https://engineering.unkey.com/contributing/quality/testing/simulation-tests.md): Property-based testing with the simulation framework
- [Unit tests](https://engineering.unkey.com/contributing/quality/testing/unit-tests.md): Table-driven patterns and unit test conventions
- [Builds](https://engineering.unkey.com/contributing/tooling/builds.md): How Unkey builds service images with Docker
- [Transactional emails](https://engineering.unkey.com/contributing/tooling/emails.md): How Go services send email and how to edit the templates
- [Feature flags](https://engineering.unkey.com/contributing/tooling/feature-flags.md): How feature flags work in the dashboard
- [Mise](https://engineering.unkey.com/contributing/tooling/mise.md): How Unkey uses mise for local tooling and repository tasks
- [Releases](https://engineering.unkey.com/contributing/tooling/releases.md): How Unkey ships service images from a git tag to production
- [Users & Roles](https://engineering.unkey.com/infra/clickhouse/index.md)
- [grafana_readonly](https://engineering.unkey.com/infra/clickhouse/roles/grafana-readonly.md)
- [insertonly_role](https://engineering.unkey.com/infra/clickhouse/roles/insertonly-role.md)
- [readonly_role](https://engineering.unkey.com/infra/clickhouse/roles/readonly-role.md): Read-only access to the default database
- [apiv2](https://engineering.unkey.com/infra/clickhouse/users/apiv2.md)
- [eve](https://engineering.unkey.com/infra/clickhouse/users/eve.md): Read-only analytics user for ad-hoc data exploration
- [frontline](https://engineering.unkey.com/infra/clickhouse/users/frontline.md)
- [github](https://engineering.unkey.com/infra/clickhouse/users/github.md)
- [grafana](https://engineering.unkey.com/infra/clickhouse/users/grafana.md)
- [unkey_admin](https://engineering.unkey.com/infra/clickhouse/users/unkey-admin.md)
- [vector](https://engineering.unkey.com/infra/clickhouse/users/vector.md)
- [vercel_dashboard](https://engineering.unkey.com/infra/clickhouse/users/vercel-dashboard.md)
- [Overview](https://engineering.unkey.com/infra/index.md): Documentation for Unkey's infrastructure.
- [PlanetScale query tags](https://engineering.unkey.com/infra/planetscale/query-insights-tags.md): SQLCommenter metadata for attributing MySQL load in PlanetScale Query Insights
- [Deploy MySQL database changes](https://engineering.unkey.com/infra/planetscale/schema-changes.md): Make safe changes to our database through PlanetScale
- [Create a key migration](https://engineering.unkey.com/infra/runbooks/key-migration.md): How to set up a key migration when a customer wants to import existing API keys into Unkey
- [Create a legacy invoice manually](https://engineering.unkey.com/infra/runbooks/legacy-billing.md): How to create and review a draft Stripe invoice for a workspace that still uses legacy billing