# Architectural Rules Enforced by Instatic's Architecture Tests: The Complete Guide
> Instatic's architecture tests enforce 18 structural and design-time invariants, breaking your build on violation. Discover the complete guide to these automated checks.
- Repository: [CoreBunch/Instatic](https://github.com/CoreBunch/Instatic)
- Tags: deep-dive
- Published: 2026-07-27
---
**Instatic enforces 18 categories of structural and design-time invariants through automated architecture tests located in `src/__tests__/architecture/*.test.ts`, which break the build immediately upon any violation.**
Instatic, developed by CoreBunch, encodes its architectural decisions as executable tests that run on every `bun test` invocation. These tests act as guardrails for module boundaries, database portability, security boundaries, and UI consistency. The following sections detail every rule encoded in the test suite, referencing the actual test files and enforced constraints found in the source code.
## Module Import and Public API Boundaries
Instatic strictly controls how modules expose and consume internal APIs to maintain stable public surfaces.
### Barrel-Import Discipline
The test [`src/__tests__/architecture/no-core-barrel-deep-imports.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/__tests__/architecture/no-core-barrel-deep-imports.test.ts) enforces that external code imports public APIs exclusively through a module’s barrel (`@core/page-tree`) and never via concrete internal paths such as `@core/page-tree/node.ts`. This prevents accidental reliance on private implementation details that may change.
```ts
// ❌ Wrong – deep import of an internal file
import { PageNode } from '@core/page-tree/node';
// ✅ Correct – use the barrel export
import { PageNode } from '@core/page-tree';
```
### Plugin Import Boundaries
Plugin bundles are prohibited from importing Node/Bun core modules or performing unauthorized I/O. The [`plugin-sandbox-invariants.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/plugin-sandbox-invariants.test.ts) and [`plugin-host-import-boundaries.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/plugin-host-import-boundaries.test.ts) tests ensure that all permissions are centrally declared and that plugin hosts do not import the API dispatch layer, preventing circular dependencies.
## Database Dialect and Storage Conventions
Instatic maintains portability between PostgreSQL and SQLite through strict SQL and schema rules.
### ANSI-SQL Compliance and JSON Handling
The [`db-postgres-isms.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/db-postgres-isms.test.ts) test bans PostgreSQL-specific syntax (`now()`, `::int`, etc.), enforcing ANSI-SQL only. Additionally, [`db-json-column-naming.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/db-json-column-naming.test.ts) requires JSON columns to end with `_json`, mapping to `jsonb` in Postgres and `text` in SQLite. All persisted JSON must pass through TypeBox helpers rather than raw `JSON.parse`, as enforced by [`json-extract-egress.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/json-extract-egress.test.ts) and [`boundary-validation.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/boundary-validation.test.ts).
```ts
// ❌ Illegal usage in a repository
await db.query('SELECT * FROM posts WHERE created_at > now()');
// ✅ ANSI-SQL compliant
await db.query('SELECT * FROM posts WHERE created_at > CURRENT_TIMESTAMP');
```
### Migration Parity and Content Storage
The [`migration-parity.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/migration-parity.test.ts) test ensures that migrations for PostgreSQL and SQLite share identical IDs and order. Content-storage conventions are enforced by [`data-tables-system-flag.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/data-tables-system-flag.test.ts), [`no-legacy-content-domain.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/no-legacy-content-domain.test.ts), and [`no-legacy-pages-table.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/no-legacy-pages-table.test.ts), which mandate that system tables (`posts`, `pages`, `components`) are seeded with `system: true`, legacy tables are eradicated, and all content lives in `data_*` tables.
## Validation and Type Safety Boundaries
Instatic uses TypeBox to maintain type safety at runtime boundaries.
### TypeBox-Only Validation
The [`boundary-validation.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/boundary-validation.test.ts) test enforces five critical rules:
1. HTTP responses must be validated with `apiRequest` or `readEnvelope`.
2. No raw `JSON.parse(... ) as` casts at persistence boundaries.
3. Admin code may only use `fetch` for a small allow-list (NDJSON streams, SVG bytes, FormData uploads).
4. Server handlers must use `readValidatedBody`.
5. After `readEnvelope` or `parseJsonResponse`, never cast fields; instead reference the proper TypeBox schema.
```ts
// ❌ Bad – raw cast
const data = JSON.parse(body) as MyType;
// ✅ Good – use TypeBox helper
import { safeParseJson } from '@core/utils/json';
const data = safeParseJson(body, MyTypeSchema);
```
### Error Handling Consistency
The [`no-inline-error-ternary.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/no-inline-error-ternary.test.ts) test requires that every `catch (err)` in admin code extract the message using `getErrorMessage(err, fallback)`, prohibiting manual ternary checks for error messages.
## Authentication and Capability Gating
Security boundaries are enforced through mandatory capability checks.
### Handler Protection
The [`cms-handlers-capability-gated.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/cms-handlers-capability-gated.test.ts) and [`capability-picker-coverage.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/capability-picker-coverage.test.ts) tests ensure that every CMS handler calls a capability check (`requireCapability`, `requireAuthenticatedUser`, etc.) and that capability metadata and client-side lists remain synchronized.
```ts
// ❌ No capability guard
export async function deletePost(req: Request) {
// …
}
// ✅ Proper guard
export async function deletePost(req: Request) {
requireCapability(req, 'cms.content.delete');
// …
}
```
## UI Architecture and Design System
Instatic enforces a strict design system through CSS and component usage rules.
### CSS Token Policies
The [`css-token-policy.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/css-token-policy.test.ts), [`no-css-var-fallbacks.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/no-css-var-fallbacks.test.ts), and [`noTailwindUtilities.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/noTailwindUtilities.test.ts) tests enforce that CSS Modules use only token variables (`var(--token)`) with no raw hex/rgb/hsl values, no fallback values in `var(--x, fallback)`, and absolutely no Tailwind utility classes or dependencies.
```tsx
// ❌ Prohibited
...
// ✅ Preferred – CSS Module with token vars
import styles from './MyComponent.module.css';
...
```
### UI Primitive Requirements
The [`button-primitive-usage.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/button-primitive-usage.test.ts), [`ui-primitives-location.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/ui-primitives-location.test.ts), and related icon tests mandate that all interactive controls use primitives under `src/ui/components/`. Bare `