# Architecture Tests in Instatic: Automated Enforcement of Structural Rules

> Discover Instatic's architecture tests that enforce structural rules. Learn how Node.js, regex, and CI integration prevent forbidden patterns, ensuring codebase integrity.

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

---

**Instatic maintains strict architectural discipline through a comprehensive suite of architecture tests located in `src/__tests__/architecture/` that scan source files using Node.js filesystem APIs and regular expressions, failing the CI pipeline immediately when forbidden patterns like Tailwind dependencies or deep barrel imports are detected.**

The CoreBunch/Instatic repository relies on automated architecture tests to prevent codebase drift and enforce structural invariants. Unlike traditional unit tests that verify runtime behavior, these tests traverse the source tree to validate import conventions, CSS policies, and database dialect rules. By failing fast during the `bun test` execution, they ensure that every pull request adheres to the project's documented architectural vision.

## How Architecture Tests Scan the Codebase

Each architecture test uses Node’s 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 error message that causes the test runner to fail.

```typescript
// Example: Running the architecture suite locally
$ bun test src/__tests__/architecture/**/*.test.ts

```

When a test detects a forbidden pattern, it pushes a violation object and throws an error, immediately blocking the CI pipeline:

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

```

## Dependency Bans and Import Discipline

### Prohibiting Tailwind Ecosystem Dependencies

The [`no-tailwind-deps.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/no-tailwind-deps.test.ts) test enforces a strict ban on Tailwind-related packages and utility libraries. The test scans [`package.json`](https://github.com/CoreBunch/Instatic/blob/main/package.json) and import statements to block `clsx`, `tailwind-merge`, `class-variance-authority`, and `@radix-ui/*`. It also prohibits `@tailwind` and `@apply` directives in any stylesheet.

### Enforcing Barrel-Only Imports

The [`no-core-barrel-deep-imports.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/no-core-barrel-deep-imports.test.ts) test ensures all external code imports core engine modules through their public barrels (`@core/page-tree`, `@core/publisher`) rather than deep-importing concrete implementation files. The test uses a regular expression to detect violations:

```typescript
// Example: Enforcing barrel imports (no-core-barrel-deep-imports.test.ts)
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 Dialect and Migration Rules

### Banning Postgres-Specific Syntax

The [`db-postgres-isms.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/db-postgres-isms.test.ts) test blocks Postgres-only SQL constructs in shared database repositories. This ensures the core engine remains portable across different database adapters.

### JSON Column Naming Conventions

The [`db-json-column-naming.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/db-json-column-naming.test.ts) test enforces that all JSON columns follow the `*_json` naming convention, maintaining consistency in schema definitions.

### Migration Parity Between Adapters

The [`migration-parity.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/migration-parity.test.ts) test verifies that every migration added for PostgreSQL has a matching SQLite counterpart with the same ID. This guarantees feature parity across supported database dialects.

## CSS Token Policy and Styling Constraints

### Design Token Enforcement

The [`css-token-policy.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/css-token-policy.test.ts) test requires all CSS modules to use design tokens (`var(--…)`) defined in [`globals.css`](https://github.com/CoreBunch/Instatic/blob/main/globals.css). It prohibits hard-coded color values or arbitrary values outside the token system.

### No Fallback Values for CSS Variables

The [`no-css-var-fallbacks.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/no-css-var-fallbacks.test.ts) test disallows fallback values in CSS custom properties. This ensures strict adherence to the design token system and prevents accidental degradation of visual consistency.

## Tree Mutation and Schema Integrity

The [`no-vc-mode-branches-in-mutations.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/no-vc-mode-branches-in-mutations.test.ts) test guarantees that tree-mutation code remains agnostic to visual-component mode. It forbids conditional checks like `kind === 'visualComponent'` in mutation logic and verifies that the legacy `childNodes` field has been removed from core schemas.

## Plugin Sandbox Security Invariants

Multiple tests enforce the plugin security model. The [`plugin-sandbox-invariants.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/plugin-sandbox-invariants.test.ts) and [`plugin-secrets-never-leak.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/plugin-secrets-never-leak.test.ts) files verify that plugin VM sandbox permissions, secret handling, and RPC registration follow strict security constraints. These tests prevent plugins from accessing unauthorized APIs or leaking sensitive configuration.

## UI and Routing Discipline

### Admin Router Usage

The [`admin-router-usage.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/admin-router-usage.test.ts) test guarantees that the admin UI uses the custom router located in `src/admin/lib/routing/` instead of `react-router-dom`. This ensures consistent navigation behavior and route guarding across the administrative interface.

### UI Primitive Enforcement

The [`button-primitive-usage.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/button-primitive-usage.test.ts) test enforces that UI components employ shared primitives (`Button`, `Input`, etc.) rather than raw HTML elements. This maintains accessibility standards and visual consistency.

### Error Boundary Coverage

The [`error-boundary-coverage.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/error-boundary-coverage.test.ts) test confirms that every error-throwing path in the UI is covered by an `ErrorBoundary`, preventing application crashes from unhandled exceptions.

### Asset Route Hygiene

The [`hole-runtime-asset-route.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/hole-runtime-asset-route.test.ts) validates that dynamic asset routes (e.g., hole runtime) are correctly defined and do not expose raw files directly, maintaining proper abstraction layers for static assets.

## Summary

- Architecture tests in `src/__tests__/architecture/` use Node.js filesystem APIs to scan source code for structural violations across TypeScript and CSS files.
- **Dependency bans** prohibit Tailwind-related packages and enforce barrel-only imports for core engine modules like `@core/page-tree`.
- **Database rules** enforce dialect portability by blocking Postgres-specific syntax, requiring `*_json` column naming, and ensuring migration parity between PostgreSQL and SQLite adapters.
- **CSS policies** mandate design tokens from [`globals.css`](https://github.com/CoreBunch/Instatic/blob/main/globals.css) while prohibiting fallback values and Tailwind directives.
- **Plugin sandbox tests** verify VM security constraints, secret handling, and RPC registration integrity.
- **UI discipline tests** enforce custom admin routing, shared primitive usage, comprehensive error boundary coverage, and safe asset route definitions.

## Frequently Asked Questions

### Where are the architecture tests located in the Instatic codebase?

All architecture tests reside in the `src/__tests__/architecture/` directory according to the CoreBunch/Instatic source code. Each test file targets a specific structural invariant, such as [`no-tailwind-deps.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/no-tailwind-deps.test.ts) for dependency management or [`migration-parity.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/migration-parity.test.ts) for database consistency.

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

While unit tests verify functional behavior of individual functions and components, architecture tests inspect file contents and directory structures using regular expressions and string scans. They enforce codebase-wide structural rules—such as banning specific import patterns or enforcing CSS token usage—by failing the build when violations are detected.

### What happens when an architecture test detects a violation?

The test aggregates all violations into a descriptive error message and throws an exception, which causes `bun test` to exit with a failure status. This immediate feedback prevents developers from merging code that violates import conventions, styling policies, or security invariants into the main branch.

### Why does Instatic ban Tailwind CSS and related utilities?

The [`no-tailwind-deps.test.ts`](https://github.com/CoreBunch/Instatic/blob/main/no-tailwind-deps.test.ts) test blocks Tailwind CSS and utility libraries like `clsx` and `class-variance-authority` to enforce a design-token-first styling approach. By requiring all styles to use CSS custom properties defined in [`globals.css`](https://github.com/CoreBunch/Instatic/blob/main/globals.css), Instatic maintains consistent theming and avoids utility-class pollution that can lead to unmaintainable stylesheets.