How Database Schemas Are Managed in i-have-adhd: Zod Runtime Validation Explained

The i-have-adhd project manages data structure integrity without a relational database by using Zod schemas for runtime validation of JSON-based skill definitions and plugin manifests.

The i-have-adhd repository implements an ADHD-friendly response system for AI coding assistants. Unlike traditional applications that rely on SQL migrations and ORM layers, this project handles database schema management through TypeScript-first validation logic that ensures data consistency at runtime.

Why i-have-adhd Uses Runtime Validation Instead of Database Schemas

The project architecture explicitly avoids relational database dependencies. Instead of maintaining migration files in a migrations/ folder or SQL schema definitions, i-have-adhd stores configuration and skill data in markdown and JSON files. This design choice eliminates the need for database connection management while requiring strict validation of data shapes when the runtime loads skill definitions or processes API requests.

The Role of Zod as the Schema Layer

According to the source code in extensions/i-have-adhd.ts, the project implements Zod—a lightweight TypeScript-first validation library—as the source of truth for all data structures. Zod schemas define the expected shape of plugin manifests, skill configurations, and request/response payloads, providing compile-time type inference and runtime safety checks.

Three Critical Schema Domains in i-have-adhd

The validation strategy covers three primary data categories that replace traditional database tables.

Skill Definition Schemas

The canonical ADHD-friendly response rules reside in skills/i-have-adhd/SKILL.md. When the runtime loads this markdown file, it validates the structure using a Zod schema defined in the extension code. This ensures that any updates to the skill documentation conform to expected formatting and metadata requirements before the skill engine processes them.

Plugin Manifest Validation

Files such as opencode.json, .claude-plugin/plugin.json, and .codex-plugin/plugin.json each have associated Zod schemas that verify required fields including $schema, model, and permission configurations. The validation logic checks these manifests before the plugin loads, preventing runtime errors from malformed configuration objects.

Runtime Request Payload Parsing

The TypeScript entry point at extensions/i-have-adhd.ts imports these schemas to parse incoming payloads from host runtimes like OpenCode, Claude, or Codex. By calling .parse() on incoming data, the system guarantees that only objects matching the expected TypeScript interfaces proceed to the skill engine, effectively preventing runtime type errors.

Implementing Schema Validation in Code

The following patterns demonstrate how i-have-adhd implements its validation layer.

Defining a Data Model Schema

import { z } from "zod";

export const TaskSchema = z.object({
  id: z.string().uuid(),
  title: z.string().min(1),
  completed: z.boolean().default(false),
  createdAt: z.coerce.date(),
});

export type Task = z.infer<typeof TaskSchema>;

Validating Incoming Runtime Data

import { TaskSchema } from "./schemas";

export async function handleRequest(rawBody: unknown) {
  const task = TaskSchema.parse(rawBody);
  return { success: true, task };
}

Plugin Manifest Structure Validation

import { z } from "zod";

export const OpencodeManifestSchema = z.object({
  $schema: z.string(),
  permission: z.object({
    "*": z.string(),
    read: z.record(z.string(), z.string()),
  }),
  model: z.string(),
  provider: z.object({
    openrouter: z.object({
      options: z.object({
        headers: z.record(z.string()),
      }),
      models: z.record(
        z.string(),
        z.object({
          options: z.object({
            provider: z.object({
              order: z.array(z.string()),
              allow_fallbacks: z.boolean(),
            }),
          }),
        })
      ),
    }),
  }),
});

Key Files Managing Schema Definitions

Understanding the repository structure requires familiarity with these specific files:

• opencode.json: Defines the primary OpenCode plugin manifest including permissions, model selection, and provider options.
• extensions/i-have-adhd.ts: Serves as the runtime entry point that imports Zod schemas and validates incoming data before invoking the skill engine.
• skills/i-have-adhd/SKILL.md: Contains the 10 ADHD-friendly response rules parsed and validated by the runtime.
• AGENTS.md: Documents how agents interact with the repository's skill and manifest organization.

Summary

• i-have-adhd replaces traditional database schemas with Zod-based runtime validation.
• Data persistence occurs through JSON files and markdown rather than relational tables.
• The extensions/i-have-adhd.ts entry point validates all incoming payloads against strict TypeScript schemas.
• Plugin manifests in opencode.json and similar files undergo schema validation before execution.
• Changes to data structures require only updating the corresponding Zod schema without migration scripts.

Frequently Asked Questions

Does i-have-adhd use SQL or an ORM for data persistence?

No. The project does not implement SQL databases or ORM layers. Instead, it stores data in JSON configuration files and markdown documentation, using Zod schemas to enforce data integrity at runtime.

How does i-have-adhd handle schema changes without database migrations?

Schema changes require only updating the relevant Zod schema definition in the TypeScript code. Since the system validates data at runtime rather than storing it in rigid database tables, no migration scripts are necessary to modify data structures.

Can I add a traditional database like PostgreSQL to i-have-adhd?

Yes. You can integrate PostgreSQL or SQLite by creating Zod schemas for your database models and using tools like zod-to-ts with an ORM to generate database schemas. The existing validation approach makes it straightforward to keep TypeScript types synchronized with database tables.

What validates the skill definitions in the markdown files?

The runtime validates skills/i-have-adhd/SKILL.md using Zod schemas imported in extensions/i-have-adhd.ts. This ensures that updates to the ADHD-friendly response rules maintain the correct structure and metadata required by the skill engine.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}