DEV Community

Cesar Escobar
Cesar Escobar

Posted on

Announcing NomoTect v1.0.0 GA: Build with Structure, Evolve with Confidence

#ai #webdev #programming #productivity

Escaping the Rails "Spaghetti" Trap: Reclaiming Architectural Integrity

Ruby on Rails has always been remarkably good at helping developers turn ideas into working applications quickly. Its conventions, integrated tooling, and opinionated approach remove a significant amount of accidental complexity from the early stages of a project.

The challenge often appears later.

As an application grows, the same flexibility that made the first version so productive can make architectural boundaries increasingly difficult to preserve. Features accumulate, domains begin to interact in unexpected ways, services take on responsibilities that were never part of their original purpose, and shared code gradually becomes a convenient place for everything that doesn't seem to belong anywhere else.

The result is not necessarily "bad code." It is often something more subtle: an application whose architecture becomes increasingly difficult to understand and, consequently, increasingly risky to change.

Rails provides excellent conventions for organizing an application, but it doesn't provide a native mechanism for enforcing the architectural boundaries that a growing enterprise application may require.

That is the problem NomoTect was built to address.

Today, I'm proud to announce the General Availability of NomoTect v1.0.0.

NomoTect is an open-source, AI-native, enterprise-ready governed application platform built on Ruby on Rails and Hotwire. It provides a structured foundation for building applications that need to remain secure, maintainable, observable, and evolvable as they grow.

The current runtime baseline is Ruby 4.0.5, Rails 8.1.3.1, and PostgreSQL 18, with Hotwire, ViewComponent, Importmap, Propshaft, Minitest, Brakeman, bundler-audit, and RuboCop forming the rest of the core development stack.

The guiding principle is straightforward:

Build with structure. Evolve with confidence.

Governed Architecture: Beyond the Scaffold

NomoTect goes beyond providing another Rails scaffold or a collection of recommended patterns. The platform introduces the concept of Governed Architecture, where architectural decisions are represented as explicit, testable rules that can be continuously validated.

At the center of this approach is the Engineering Constitution.

The Constitution establishes the rules that govern the platform, including architectural boundaries, dependency rules, quality expectations, documentation requirements, security principles, and the platform's Definition of Done. Instead of treating these rules as documentation that developers are expected to remember, NomoTect makes them part of the repository's executable governance model.

This results in several important capabilities.

Explicit Module Boundaries

NomoTect defines explicit boundaries between domains and modules, making responsibilities and dependencies visible rather than relying exclusively on convention.

The goal isn't to prevent modules from interacting. It is to make those interactions intentional and observable, reducing unintended coupling and context leakage as the application evolves.

Executable Contracts

Relationships between modules are represented through contracts that can be validated automatically.

This turns architectural assumptions into something the repository can actually verify. When the system changes, the contracts provide a mechanism for detecting whether those changes are still consistent with the architecture.

Repository-Native Documentation

Architecture documentation lives alongside the source code and is treated as part of the engineering system.

NomoTect includes documentation ownership and freshness validation, as well as continuously tested examples. This helps address one of the common problems with architecture documentation: the longer a project lives, the greater the distance can become between what the documentation says and what the repository actually does.

Secure by Default: Multi-Tenancy and Hard Isolation

For enterprise applications, architectural integrity cannot be separated from security.

NomoTect uses a deny-by-default authorization model, meaning access must be explicitly granted rather than implicitly assumed. Multi-tenancy is also treated as an architectural concern rather than simply adding a tenant_id to application tables.

The platform provides organization, membership, and role management together with explicit tenant context and tenant-safe services. Ownership transfer and cross-tenant isolation are also covered by the platform's validation and testing strategy.

The security baseline extends beyond authorization and tenant isolation.

Key capabilities include:

  • Tenant-Safe Isolation: Organization context, memberships, roles, tenant selection, ownership transfer, and cross-tenant leakage testing.
  • Supply Chain Transparency: Automated SBOM generation, dependency security automation, and OIDC provenance attestations for releases.
  • Hardened Operations: CSP and security headers, throttling and abuse controls, secret validation, and security automation.
  • Privacy: Privacy-oriented workflows and support for LGPD-related requirements.
  • Operational Security: Backup, recovery, deployment, diagnostics, and operational readiness contracts.

The objective is not to claim that a framework can make an application secure by itself. Instead, NomoTect provides a foundation in which security-related behaviors and boundaries are explicit parts of the platform architecture.

AI-Native Engineering: Repository Intelligence via MCP

One of the areas where NomoTect evolved significantly during development was the relationship between software architecture and AI-assisted development.

AI coding agents can generate code extremely quickly, but code generation alone doesn't give an agent an understanding of the architectural constraints of the repository it is modifying.

An agent may be able to see a class, but not necessarily understand why a dependency is forbidden. It may be able to find a service, but not know which module contract it is expected to satisfy.

NomoTect addresses this through Repository Intelligence.

Repository Intelligence provides deterministic architecture evidence, impact analysis, health and readiness reporting, executable playbooks, machine-readable module contracts, and a normalized governance graph.

The functionality is exposed through the platform's Ruby command interface:

# Generate architecture evidence and refresh the governance graph
ruby bin/repository-intelligence generate

# Validate module contracts against the Engineering Constitution
ruby bin/repository-intelligence validate

# Report on repository health and operational readiness
ruby bin/repository-intelligence health
ruby bin/repository-intelligence readiness

# Query repository intelligence
ruby bin/repository-intelligence query statistics

# Inspect available playbooks
ruby bin/repository-intelligence playbook list
Enter fullscreen mode Exit fullscreen mode

NomoTect can also expose this repository intelligence through a read-only-by-default MCP server:

ruby bin/repository-intelligence mcp
Enter fullscreen mode Exit fullscreen mode

The initial MCP-first adoption path is designed around the Antigravity CLI (agy) as a client. The important distinction is that agy is not the command interface for Repository Intelligence itself. The repository owns the intelligence layer, while MCP provides a standardized way for AI clients to consume that information.

This makes the architecture provider-neutral. NomoTect doesn't require a proprietary AI provider to understand its own architecture.

The larger idea is that AI agents should not have to infer every architectural constraint from source code alone. A repository can provide structured evidence about its own boundaries, contracts, health, and operational state, giving agents a much stronger basis for making changes safely.

The Complete Foundation: Feature Highlights

Repository Intelligence is only one part of NomoTect. The v1.0.0 release brings together the application capabilities developed throughout Epics 0 through 10.

Feature Category Key Capability
Domain Framework Contracted operations, queries, policies, events, and rich-domain conventions
Grid Engine Grid DSL, query AST, Active Record/Arel and Tabulator adapters, saved views, exports, and column personalization
Design System Hotwire, ViewComponent, compiled design tokens, accessibility, Light/Dark themes, and EN/PT-BR internationalization
Enterprise Services Auditability, observability, background jobs, idempotency, notifications, files, imports/exports, workflows, integrations, webhooks, and feature flags
Multi-Tenancy Organizations, memberships, roles, tenant context, ownership transfer, and tenant-safe services
Security & Privacy CSP, secure headers, throttling, secret management, privacy workflows, dependency security, SBOMs, and provenance
Repository Intelligence Architecture evidence, governance graph, contracts, impact analysis, health/readiness, playbooks, and MCP
Operations Installation, upgrades, recovery, deployment profiles, diagnostics, and operational readiness
Distribution Versioned Application Starter, container images, GitHub Releases, GHCR publication, and release certification

The platform is designed so these capabilities operate as a cohesive foundation rather than as unrelated components that an application team has to assemble and govern independently.

Developer Experience: From Installation to Production

A platform intended for real application development needs a straightforward path from evaluation to production.

For local evaluation, the shortest supported path is Docker Compose:

docker compose up --build
Enter fullscreen mode Exit fullscreen mode

Then open:

http://localhost:3000
Enter fullscreen mode Exit fullscreen mode

The development profile starts PostgreSQL 18 and enables the protected first-run installation flow. The wizard configures the application, provisions and verifies the database, creates the global platform administrator and initial organization owner, records completion evidence, and closes installer access after completion.

For developers working directly with Ruby and PostgreSQL, the standard setup is:

bash bin/setup
bash bin/dev
Enter fullscreen mode Exit fullscreen mode

For a new installation managed through the interactive wizard, the repository also supports explicit installation configuration:

INSTALLATION_ENABLED=true \
PGHOST=127.0.0.1 \
PGUSER=postgres \
PGPASSWORD=postgres \
bash bin/setup

INSTALLATION_ENABLED=true \
PGHOST=127.0.0.1 \
PGUSER=postgres \
PGPASSWORD=postgres \
bash bin/dev
Enter fullscreen mode Exit fullscreen mode

Production installations require operator-provided bootstrap tokens and appropriate secret configuration. Default or example credentials should never be used in deployed environments.

The complete local verification pipeline can be run with:

bash bin/ci
Enter fullscreen mode Exit fullscreen mode

Application Starter: From Platform to Product

One of the lessons from building NomoTect was that a contributor repository and a product starting point serve different purposes.

For new products, NomoTect therefore provides a versioned Application Starter distribution.

Instead of cloning the contributor repository and then removing the project's development history, documentation, and contributor-specific concerns, the Starter provides a clean baseline intended for the application that will actually be built.

This creates a clearer separation between the platform and the products built on top of it.

The current release provides distribution profiles for Docker Compose, Dev Containers and Codespaces, Kamal, private VPS deployments, Render, OCI images, GitHub Releases, and GHCR publication.

The Application Starter documentation provides the onboarding details.

The Road to v1.0.0: Epics 0 Through 10

NomoTect v1.0.0 is the result of eleven development epics, starting with the project foundation and ending with stable-release validation.

Epic 0 — Project Foundation established the Apache 2.0 identity, Engineering Constitution, architecture and dependency rules, quality model, documentation governance, security disclosure, and contribution workflow.

Epic 1 — Platform Core introduced the Rails and PostgreSQL foundation together with Hotwire, ViewComponent, authentication, deny-by-default authorization, request context, health checks, logging, and the initial CI security pipeline.

Epic 2 — Design System and i18n established the design tokens, typography, icons, layouts, form and navigation components, accessibility baseline, and English/Brazilian Portuguese internationalization.

Epic 3 — Grid Engine introduced the Grid DSL, registries, query AST, database adapters, Tabulator integration, HTML/Turbo fallback, saved views, export, and column personalization.

Epic 4 — Domain Framework and Reference Application established operations, queries, policies, events, domain conventions, and the reference Customers capability.

Epic 5 — Enterprise Services expanded the platform with audit and observability, background jobs, idempotency, notifications, files, imports and exports, workflows, integrations, webhooks, and feature flags.

Epic 6 — Multi-Tenant Platform introduced organizations, memberships, roles, invitations, tenant selection and context, tenant-safe services, ownership transfer, and cross-tenant isolation guarantees.

Epic 7 — Security and Privacy added privacy and LGPD workflows, CSP and secure headers, throttling, secret and key management, dependency and supply-chain automation, SBOM/provenance, and threat/security suites.

Epic 8 — AI Platform and Repository Intelligence introduced provider-neutral repository scanning, the governance graph and SQLite store, machine-readable contracts, generated evidence, playbooks, MCP, health/readiness reporting, and clean-worktree certification.

Epic 9 — Distribution, Installation and Enterprise Extensions brought protected installation, packaging and deployment, upgrades and recovery, release engineering, publication, extension contracts, operational readiness, and operator documentation.

Finally, Epic 10 — Framework Validation and Stable Release focused on representative application validation, release candidates, cross-cutting quality certification, OIDC provenance attestations, and the final v1.0.0 GA release gate.

All Epics 0 through 10 are now complete and validated.

The detailed roadmap and delivery evidence are available in the authoritative roadmap, while the specific criteria for the stable release are documented in the v1.0.0 Release Gate.

What GA Means for NomoTect

General Availability is an important milestone, but it does not mean that NomoTect is a finished or frozen platform.

It means that the foundation has reached the maturity level defined by the project for a stable release. The architectural model, contracts, security baseline, operational workflows, distribution paths, documentation, Repository Intelligence, and release process have all been validated as part of the Epics 0–10 delivery.

The stable v1.0.0 release is published with OIDC provenance attestations, container images on GHCR, and standalone bootstrap certification.

The platform is now in a position where the next stage of validation comes from something different: real applications built by people who weren't involved in creating the platform itself.

That is a much more interesting test.

Join the Ecosystem

NomoTect is distributed under the Apache License 2.0.

The community platform provides the governed application foundation, while organizations can build compatible applications, services, and extensions around it.

If you want to explore the project, these are the best places to start:

If the problem you're dealing with is not how to build a Rails application quickly, but how to keep a growing Rails application understandable and safe to change, NomoTect is an experiment worth exploring.

Build with structure. Evolve with confidence.

Top comments (0)