GrimleyTK: Declarative Data Architecture as a First-Class Concern

Modern software systems rarely fail because of missing features.
 They fail because data ownership becomes unclear, boundaries blur, and architectural decisions silently degrade over time.

Shared databases, implicit contracts between services, and ad-hoc schema evolution are still extremely common even in systems that claim to follow microservice principles.

This post introduces GrimleyTK, an open-source CLI toolkit designed to treat data architecture as a first-class, declarative concern.

The problem: implicit data architecture

In many distributed systems, data architecture emerges accidentally.

Some common patterns:

• Multiple services share the same database
• Ownership of tables is undocumented or tribal knowledge
• Cross-service reads are done directly, without constraints
• Schema changes are applied manually or via ad-hoc scripts
• Architectural violations are only discovered in production

Even teams with good intentions often end up with:

• tight coupling through the database
• unclear responsibility boundaries
• fear of schema evolution

The core issue is not tooling, it is the lack of an explicit, enforceable model for data architecture.

Existing tools don’t fully solve this

Traditional tools focus on how to apply changes:

• ORMs abstract database access
• Migration tools apply incremental schema changes
• SQL linters validate syntax and style

These tools are useful, but they do not answer architectural questions, such as:

• Who owns this table?
• Which services are allowed to read this data?
• Is this cross-domain access intentional?
• Are sensitive columns being exposed?
• Is this schema evolution architecturally valid?

These questions usually live in documents if they exist at all.

GrimleyTK’s approach

GrimleyTK starts from a different premise:

Data architecture should be explicit, declarative, validated, and enforceable, before touching the database.

Instead of treating the database as an implementation detail, GrimleyTK treats it as an architectural boundary.

The core ideas are:

• Explicit ownership: every table belongs to exactly one domain
• Explicit read models: cross-domain reads must be declared
• Declarative architecture: a single source of truth (grimley.yaml)
• Validation before execution: architectural rules are enforced early
• Safe evolution: changes are planned and reviewed before being applied

Declarative architecture with grimley.yaml

At the center of GrimleyTK is a declarative configuration file:

domains:
  catalog:
    schema: catalog
    owns:
      tables:
        products:
          columns:
            id:
              type: uuid
              primary_key: true
            price:
              type: numeric

  wishlist:
    reads:
      products_view:
        from: catalog.products
        columns: [id, price]

This file describes intent, not implementation details.

From this declaration, GrimleyTK can:

• validate architectural constraints
• generate a database execution plan
• apply changes safely using transactions

Validation as an architectural guardrail

GrimleyTK includes multiple layers of validation:

• Structural: is the configuration well-formed?
• Referential: do referenced tables and columns exist?
• Architectural: are ownership and boundaries respected?
• Security: are sensitive columns exposed across domains?

Architectural violations are detected before any SQL is generated or executed.

This shifts architectural correctness from runtime to design time.

Planning before execution

Instead of directly mutating the database, GrimleyTK introduces a planning step:

grimleytk plan

This command generates a dry-run execution plan, showing exactly which SQL statements would be applied.

Only after reviewing the plan does the user explicitly execute:

grimleytk apply

Execution is:

• transactional
• explicit
• opt-in
• safe by default

What GrimleyTK is, and is not

GrimleyTK is:

• a data architecture governance tool
• a declarative modeling CLI
• a validation and planning layer for databases

GrimleyTK is not:

• an ORM
• a replacement for migrations
• a fully automated schema diff engine (yet)

This scope is intentional. The goal is architectural clarity, not automation for its own sake.

Current state and roadmap

GrimleyTK is currently released as an MVP with:

• declarative modeling
• architectural validation
• SQL planning
• safe apply for PostgreSQL

Future directions include:

• schema diffing
• drift detection
• permission and RLS generation
• additional database engines

All evolution will be guided by real-world usage and feedback.

Why this project exists

GrimleyTK exists because data architecture decisions are often:

• implicit
• under-documented
• hard to enforce
• expensive to fix later

By making these decisions explicit and machine-verifiable, teams can evolve systems with more confidence and less fear.

Project

GrimleyTK is open-source and available on GitHub:
 👉 https://github.com/MatheusPereiraSilva/grimleytk

Feedback, discussion, and critical questions are welcome.

Final note

This project is not about enforcing one “correct” architecture.

It is about making architectural intent explicit, so that teams can reason, discuss, and evolve systems deliberately instead of accidentally.