# Architectural Rules Enforced by Instatic's Test Suite: 18 Critical Constraints
> Discover Instatic's 18 architectural rules enforced by its test suite. Learn how it maintains code quality by preventing violations of import discipline, SQL compliance, and more.
- Repository: [CoreBunch/Instatic](https://github.com/CoreBunch/Instatic)
- Tags: architecture
- Published: 2026-07-03
---
**Instatic encodes 18 categories of structural and design-time invariants as automated architecture tests in `src/__tests__/architecture/*.test.ts`, breaking the build on violations of barrel-import discipline, ANSI-SQL compliance, TypeBox validation boundaries, and plugin sandbox isolation.**
Instatic, maintained by CoreBunch, treats architectural decisions as executable code. The test suite located in `src/__tests__/architecture/` runs on every `bun test` invocation, enforcing contracts that span database portability, UI consistency, and security boundaries. These tests ensure that the codebase remains free of circular dependencies, unauthorized capability access, and framework-specific lock-in.
## Module Import Discipline
### Barrel-Import Enforcement
The test [`no-core-barrel-deep-imports.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/no-core-barrel-deep-imports.test.ts) mandates that all external code import public APIs through module barrels rather than internal file paths. This preserves public surface stability and prevents accidental coupling to private implementation details.
```ts
// ❌ Wrong – violates no-core-barrel-deep-imports.test.ts
import { PageNode } from '@core/page-tree/node';
// ✅ Correct – uses the barrel export
import { PageNode } from '@core/page-tree';
```
## Database Portability and Schema Rules
### ANSI-SQL Compliance
[`db-postgres-isms.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/db-postgres-isms.test.ts) bans PostgreSQL-specific syntax (`now()`, `::int`, etc.) to maintain cross-database compatibility. Only ANSI-SQL constructs are permitted, ensuring the application runs identically on both PostgreSQL and SQLite.
```ts
// ❌ Illegal – fails db-postgres-isms.test.ts
await db.query('SELECT * FROM posts WHERE created_at > now()');
// ✅ Compliant – ANSI-SQL
await db.query('SELECT * FROM posts WHERE created_at > CURRENT_TIMESTAMP');
```
### JSON Column Conventions
[`db-json-column-naming.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/db-json-column-naming.test.ts) enforces that all JSON columns end with the `_json` suffix. This allows the database layer to map Postgres `jsonb` types to SQLite `text` types automatically without schema drift.
### Migration Parity
[`migration-parity.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/migration-parity.test.ts) ensures that PostgreSQL and SQLite migrations share identical IDs and execution order, preventing environment-specific schema divergence.
### Content Storage Invariants
Tests including [`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) enforce that:
- System tables (`posts`, `pages`, `components`) are seeded with `system: true`
- No legacy `pages` or `page_versions` tables exist
- All content lives in `data_*` tables
## Validation and Type Safety
### TypeBox Boundary Validation
[`boundary-validation.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/boundary-validation.test.ts) defines five strict rules for data validation:
1. HTTP responses must use `apiRequest` or `readEnvelope`
2. Raw `JSON.parse(... ) as` casts are prohibited at persistence boundaries
3. Admin code `fetch` usage is restricted to an allow-list (NDJSON streams, SVG bytes, FormData uploads)
4. Server handlers must use `readValidatedBody`
5. Post-validation, fields must reference TypeBox schemas rather than manual casting
```ts
// ❌ Fails boundary-validation.test.ts
const data = JSON.parse(body) as MyType;
// ✅ Valid – uses TypeBox helper
import { safeParseJson } from '@core/utils/json';
const data = safeParseJson(body, MyTypeSchema);
```
### Error Handling Consistency
[`no-inline-error-ternary.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/no-inline-error-ternary.test.ts) requires that every `catch (err)` block in admin code extract messages via `getErrorMessage(err, fallback)`, prohibiting manual ternary error checks.
## Security and Capability Gating
### Handler Protection
[`cms-handlers-capability-gated.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/cms-handlers-capability-gated.test.ts) mandates that every CMS handler calls a capability check such as `requireCapability` or `requireAuthenticatedUser` before executing logic.
```ts
// ❌ Missing capability guard – will fail
export async function deletePost(req: Request) {
// ...
}
// ✅ Protected – passes capability gating
export async function deletePost(req: Request) {
requireCapability(req, 'cms.content.delete');
// ...
}
```
### Metadata Synchronization
[`capability-picker-coverage.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/capability-picker-coverage.test.ts) ensures that capability metadata and client-side capability lists remain synchronized, preventing authorization gaps between server and UI.
## Design System and Styling Constraints
### CSS Token Policies
[`css-token-policy.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/css-token-policy.test.ts) and [`no-css-var-fallbacks.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/no-css-var-fallbacks.test.ts) enforce that CSS Modules use only token variables (`var(--token)`) without raw hex/rgb/hsl values or fallback values in `var(--x, fallback)`.
### Tailwind Prohibition
[`noTailwindUtilities.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/noTailwindUtilities.test.ts) and [`no-tailwind-deps.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/no-tailwind-deps.test.ts) completely ban Tailwind utility classes and related dependencies, enforcing a CSS Modules-only architecture.
```tsx
// ❌ Prohibited by noTailwindUtilities.test.ts
...
// ✅ Preferred – CSS Module with token vars
import styles from './MyComponent.module.css';
...
```
### UI Primitive Requirements
Six tests ([`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), [`no-native-browser-dialogs.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/no-native-browser-dialogs.test.ts), [`no-native-title-tooltips.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/no-native-title-tooltips.test.ts), [`no-third-party-icons.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/no-third-party-icons.test.ts), [`direct-icon-imports.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/direct-icon-imports.test.ts)) enforce that:
- Interactive controls use primitives under `src/ui/components/`
- Bare `