# What Architecture Tests Enforce Structural Rules in the Instatic Codebase

> Discover how Instatic architecture tests enforce structural rules. Learn about forbidden patterns, import conventions, and design token validation in the Instatic codebase.

- Repository: [CoreBunch/Instatic](https://github.com/CoreBunch/Instatic)
- Tags: architecture
- Published: 2026-08-01

---

**Instatic maintains strict structural integrity through a comprehensive suite of architecture tests located in `src/__tests__/architecture/` that scan source files for forbidden patterns, enforce import conventions, and validate design tokens across the codebase.**

The CoreBunch/Instatic repository uses automated architectural guardrails to prevent codebase drift and preserve clean separation of concerns. These tests run on every pull request via `bun test`, failing the CI pipeline immediately when violations are detected.

## Dependency and Import Constraints

### Banning Tailwind Ecosystem Dependencies

The [`src/__tests__/architecture/no-tailwind-deps.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/__tests__/architecture/no-tailwind-deps.test.ts) test enforces a strict **dependency ban** on the entire Tailwind ecosystem. It scans all [`package.json`](https://github.com/CoreBunch/Instatic/blob/main/package.json) files and TypeScript imports to block packages including `clsx`, `tailwind-merge`, `class-variance-authority`, and any `@radix-ui/*` scoped packages. The test also prohibits `@tailwind` and `@apply` directives in CSS files, ensuring the codebase maintains its design-token-first styling approach without Tailwind abstractions.

### Enforcing Barrel-Only Imports

Deep imports into core engine modules are forbidden by [`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). This test guarantees that all external code imports from public barrels like `@core/page-tree` and `@core/publisher` rather than reaching into concrete implementation files. It uses a regular expression to detect violations:

```typescript
const DEEP_IMPORT = new RegExp(
  `(?:from|import\\()\\s*['"]@core/(?:${BARRELLED_MODULES.join('|')})/[^'"]+['"]`,
);
if (DEEP_IMPORT.test(line)) {
  violations.push(`${filePath.replace(ROOT + '/', '')}:${i + 1}  ${line.trim()}`);
}

```

## Database and Migration Standards

### SQL Dialect Neutrality

The [`src/__tests__/architecture/db-postgres-isms.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/__tests__/architecture/db-postgres-isms.test.ts) test bans PostgreSQL-specific syntax in shared repository code, ensuring database portability. This prevents adapter-specific features from leaking into the core data layer, keeping the ORM dialect-agnostic.

### JSON Column Naming Conventions

All JSON columns must follow the `*_json` naming convention, enforced by [`src/__tests__/architecture/db-json-column-naming.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/__tests__/architecture/db-json-column-naming.test.ts). This structural rule makes schema inspection predictable and distinguishes JSON-structured data from plain text or relational columns.

### Cross-Adapter Migration Parity

The [`src/__tests__/architecture/migration-parity.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/__tests__/architecture/migration-parity.test.ts) test verifies that every migration added for PostgreSQL has a matching SQLite counterpart with the identical migration ID. This guarantees feature parity across supported database adapters and prevents drift between environments.

## UI Component and Styling Rules

### CSS Design Token Policy

Two complementary tests enforce the **CSS token policy**. [`src/__tests__/architecture/css-token-policy.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/__tests__/architecture/css-token-policy.test.ts) requires all CSS modules to use `var(--...)` references defined in [`globals.css`](https://github.com/CoreBunch/Instatic/blob/main/globals.css), while [`src/__tests__/architecture/no-css-var-fallbacks.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/__tests__/architecture/no-css-var-fallbacks.test.ts) explicitly prohibits fallback values in those variable references. Together, they eliminate hard-coded colors and ensure the design system remains the single source of truth for theming.

### Admin Router Enforcement

The admin UI must use the custom routing implementation from `src/admin/lib/routing/` instead of `react-router-dom`, as mandated by [`src/__tests__/architecture/admin-router-usage.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/__tests__/architecture/admin-router-usage.test.ts). This ensures consistent navigation patterns and middleware integration across the administrative interface.

### Primitive Component Usage

[`src/__tests__/architecture/button-primitive-usage.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/__tests__/architecture/button-primitive-usage.test.ts) and related tests enforce that UI components employ shared primitives (`Button`, `Input`, etc.) rather than raw HTML elements. This maintains accessibility standards and consistent interaction patterns throughout the application.

### Error Boundary Coverage

Every error-throwing path must be covered by an `ErrorBoundary` in the UI, according to [`src/__tests__/architecture/error-boundary-coverage.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/__tests__/architecture/error-boundary-coverage.test.ts). This structural rule prevents uncaught exceptions from crashing the user interface.

## Security and Plugin Architecture

### Sandbox Permission Validation

[`src/__tests__/architecture/plugin-sandbox-invariants.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/__tests__/architecture/plugin-sandbox-invariants.test.ts) validates that plugin VM sandbox permissions follow the documented security model. It checks that RPC registrations and capability grants align with the principle of least privilege.

### Secret Handling Verification

The [`src/__tests__/architecture/plugin-secrets-never-leak.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/__tests__/architecture/plugin-secrets-never-leak.test.ts) test ensures that secrets provided to plugins remain confined to the sandbox environment and cannot be exfiltrated through logging or network requests.

### Asset Route Hygiene

Dynamic asset routes—such as those used by the hole runtime—are validated by [`src/__tests__/architecture/hole-runtime-asset-route.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/__tests__/architecture/hole-runtime-asset-route.test.ts) to ensure they do not expose raw files or bypass access controls.

## Tree Mutation Integrity

### Mutation Purity Constraints

[`src/__tests__/architecture/no-vc-mode-branches-in-mutations.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/__tests__/architecture/no-vc-mode-branches-in-mutations.test.ts) enforces that tree mutation code remains agnostic to visual-component mode. It specifically forbids checks like `kind === 'visualComponent'` in mutation logic and verifies that the legacy `childNodes` field has been removed from core schemas, ensuring mutations operate purely on the abstract tree structure.

## How Architecture Tests Scan Source Files

Each architecture test uses Node.js filesystem APIs (`readdirSync`, `readFileSync`) to collect relevant TypeScript, TSX, and CSS files. The tests apply regular-expression scans or string checks to file contents, aggregating violations into an array that causes the test to `throw new Error` when non-empty:

```typescript
// Example: Pattern matching from no-tailwind-deps.test.ts
if (banned.pattern.test(src)) {
  violations.push({ file: relative(SRC_ROOT, f), pkg: banned.name })
}

```

Run the full architecture suite locally with:

```bash
bun test src/__tests__/architecture/**/*.test.ts

```

Because these tests execute as part of the standard test suite, any stray import, disallowed CSS token, or structural violation fails the build immediately, preventing architectural drift from reaching production.

## Summary

- **Dependency control**: Bans Tailwind ecosystem packages and enforces barrel-only imports for core modules via regex scanning in [`no-tailwind-deps.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/no-tailwind-deps.test.ts) and [`no-core-barrel-deep-imports.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/no-core-barrel-deep-imports.test.ts).
- **Database integrity**: Ensures dialect-agnostic SQL, consistent JSON column naming (`*_json`), and migration parity between PostgreSQL and SQLite adapters.
- **Styling governance**: Mandates CSS custom properties from [`globals.css`](https://github.com/CoreBunch/Instatic/blob/main/globals.css) while prohibiting fallbacks and Tailwind directives.
- **Security posture**: Validates plugin sandbox invariants and secret isolation through dedicated security tests.
- **Structural purity**: Enforces tree-mutation agnosticism and removal of deprecated fields like `childNodes`.

## Frequently Asked Questions

### How do architecture tests differ from unit tests in Instatic?

Architecture tests validate structural constraints across the entire codebase rather than testing individual function behavior. They scan files using regex and AST-like pattern matching to enforce import disciplines, naming conventions, and dependency bans, whereas unit tests verify specific runtime logic and data transformations.

### What happens when an architecture test fails in CI?

When a violation is detected, the test aggregates the offending file paths and patterns into an error message and calls `throw new Error`, which causes `bun test` to exit with a non-zero status. This immediately blocks the pull request from merging until the structural violation is remediated.

### Why does Instatic enforce barrel-only imports for core modules?

Barrel imports create a clear public API boundary for the `@core/*` modules, preventing consumers from depending on internal implementation details that may change. This encapsulation allows the CoreBunch team to refactor internal file structures without breaking downstream imports.

### How does the CSS token policy maintain design consistency?

By requiring all CSS modules to reference tokens defined in [`globals.css`](https://github.com/CoreBunch/Instatic/blob/main/globals.css) via `var(--...)` and prohibiting hard-coded values or fallbacks, the architecture tests ensure that theming, dark mode, and brand colors remain centralized and consistent across the entire application surface.