DEV Community: HomelessCoder

AI Tool-Calling: Translating Business Requirements to Database Schemas

HomelessCoder — Sun, 12 Jul 2026 19:51:07 +0000

Part 2 of the Omnismith "Core Platform Capabilities" series

Integrated AI assistants can map natural language schema requirements to operational APIs, deploying complete database schemas and demo datasets in real time.

The initial setup of an entity database with integrated telemetry requires substantial manual configuration. Developers building solutions for clients and technical operators bootstrapping operations must define schema structures, configure API endpoints, and establish relational integrity between physical assets and time-series logs before a single metric can be ingested. This initialization phase delays functional deployment and increases setup friction.

Omnismith addresses this setup delay by exposing its backend OpenAPI specification directly to an integrated AI Assistant. This architecture allows the assistant to interpret structured schema requirements written in natural language, map them to operational API endpoints, and deploy completed schemas on a blank project in real time.

The AI-Assisted Cold-Chain Fleet Management Schema

To bypass this manual boilerplate, a user can submit a single, plain-text request directly to the Omnismith AI Assistant interface:

"Create a fleet management schema with Vehicles, Shipments, and Drivers. Link shipments to vehicles and drivers, and track temperature and fuel metrics on vehicles."

The AI Assistant directly parses this requirement, coordinates the dependent operations, and executes the necessary API calls in sequence against the live platform.

Step 1: Automated Model Scaffolding

Upon receiving the prompt, the assistant acts as a high-level database orchestrator. It immediately identifies the three primary entities: Vehicles, Drivers, and Shipments.

To minimize network overhead, the assistant calls a consolidated system orchestration tool, scaffold_data_model, to register the core templates and their initial properties inside the dynamic Entity-Attribute-Value (EAV) database:

Vehicle Generation

The assistant identifies the requirement to track identity, model, fuel, and temperature. It packages these into the first scaffold payload:

Tool: scaffold_data_model
Payload:

{
  "templateName": "Vehicle",
  "attributes": [
    {"name": "Vehicle ID", "type": "text"},
    {"name": "Make/Model", "type": "text"},
    {"name": "Fuel Level", "type": "number"},
    {"name": "Temperature", "type": "number"}
  ]
}

Driver Generation

The assistant scaffolds the profile template required to represent staff records:

Tool: scaffold_data_model
Payload:

{
  "templateName": "Driver",
  "attributes": [
    {"name": "Driver Name", "type": "text"},
    {"name": "License Number", "type": "text"}
  ]
}

Shipment Generation

The assistant maps out the shipment record structure, registering placeholders for relational references pointing to the driver and vehicle:

Tool: scaffold_data_model
Payload:

{
  "templateName": "Shipment",
  "attributes": [
    {"name": "Shipment ID", "type": "text"},
    {"name": "Destination", "type": "text"},
    {"name": "Assigned Vehicle", "type": "reference"},
    {"name": "Assigned Driver", "type": "reference"}
  ]
}

Step 2: Closed-Loop Validation and Refinement

Omnismith utilizes a closed-loop validation engine. To verify complete execution, the assistant reads the newly deployed schema back from the platform and evaluates it against the logical requirements.

This verification pass ensures structural and temporal properties are precisely configured before telemetry ingestion begins. The assistant executes a target refinement step:

Telemetry Metric Promotion: The initial scaffolding pass registered the Fuel Level and Temperature fields as baseline numerical attributes. To support high-frequency time-series chart streaming, the validation loop promotes both fields to telemetry-optimized metric fields (data_type: 1).

Step 3: Establishing Referential Integrity

With clean template shapes in place, the assistant completes the schema by weaving the logical connections between the templates.

It maps the dynamic reference parameters on the Shipment template, instructing the relational system to look up concrete, real-time records from the Vehicle and Driver registries:

Vehicle Link: The assistant maps the Assigned Vehicle reference attribute directly to the display attribute of the target Vehicle template.
Driver Link: The assistant repeats the relational mapping for the operator records.

Because the Omnismith database engine runs on a fully dynamic runtime schema, these alterations execute instantly with no physical database migration files, zero downtime, and zero manual endpoint compilation.

Structural and Behavioral Tradeoffs

Conversational schema scaffolding trades absolute, deterministic predictability for rapid development speed.

When developers write declarative ORM schemas, migration scripts, or JSON configuration models, the resulting environment matches the written code exactly. When relying on an LLM-driven assistant, overly descriptive instructions or grammatical nuances can sometimes require structural verification passes.

To offset these behavioral risks, Omnismith relies on two structural guardrails:

Closed-Loop Verification: The agent continuously diffs the deployed API state against the intended design model, using targeted calls to refine structural details on the fly.
Visual Verification Layer: The resulting schema displays immediately in the web application's Template Library and Attribute Library. This allows developers to manually tune specific relationship constraints, tweak validation parameters, or tighten boundary conditions before ingesting operational telemetry.

Populating the Schema: Conversational Entity Ingestion

With the database structure actively running, the AI Assistant can manage concrete records within the newly established dynamic templates. Operators can query, analyze, and seed the environment.

To prepare the environment for operational testing, a user can submit a direct request to populate the fleet system:

"Generate realistic demo data for this project. Requirements: minimum 5 drivers, 7 vehicles, and 4 shipments. Ensure the dataset reflects diverse business scenarios and edge cases"

Because shipments contain strict relational constraints—requiring references to physical vehicles and registered drivers—the AI Assistant cannot execute these creations as a single batch. It coordinates a logical multi-step deployment strategy shown in the interface trace:

Independent Ingestion: The assistant first registers the independent primary resources. It calls create_entity 12 consecutive times to instantiate 5 unique driver profiles and 7 physical fleet vehicles with varied baselines.
Reference Resolution: To link the upcoming shipment logs to these exact entries, the assistant executes 2 calls to search_entities. This returns the dynamic database state, mapping the human-readable driver names and vehicle license IDs to their platform-generated UUIDv7 keys.
Relational Ingestion: With the required reference keys resolved, the assistant executes the final 4 create_entity calls. This populates the Shipment records, mapping individual waybills to the resolved vehicle and driver identifiers while introducing complex logistics parameters (such as sub-zero frozen cargo targets and baseline fuel levels).

The resulting records populate the system instantly, providing technical operators with a functional sandbox that models actual business environments.

Omnismith, AI Assistant, Creating Records Using Natural Language

Omnismith, Vehicle Template, Entity Search Page

Omnismith, Vehicle Entity Quick Edit Dialog

Omnismith, Vehicle Entity Audit Log

Operational Readiness

The finalized schema produces an immediately queryable, typed database structure. Every template and attribute is initialized with a distinct, immutable UUIDv7. The platform is ready to accept ingestion streams and transactional updates immediately:

Real-time Ingestion: Temperature sensors mounted on fleet assets can start streaming sensor metrics straight to the platform's high-volume metric stream using the endpoint: POST /v1/entities/{entity_id}/metrics. This bypasses the primary document update path, sending values directly to TimescaleDB for sub-second chart visualization.
Relational Search Queries: The query engine natively resolves the references established by the assistant. Operators can run complex queries to filter all active Shipment entities associated with a specific vehicle ID where the vehicle state is flagged as active.
Audit Trailing: Any change to these attributes is continuously written to an append-only transaction ledger on TimescaleDB, detailing what changed, when, and by whom from the first second of deployment.

The cold-chain fleet management model developed in this guide illustrates how natural language requirements map directly to relational schemas and telemetry databases. While built for logistics, these same AI-driven scaffolding and conversational ingestion mechanics apply to any operational domain, from facility management to hardware infrastructure tracking.

In the next entry of this series, the platform will utilize this active cold-chain database to demonstrate dynamic automations, configure multi-role access controls (RBAC/ABAC), and build real-time monitoring dashboards.

The Manual REST Alternative

To understand how the AI Assistant automates schema deployment, it is valuable to look at how a developer constructs this exact environment manually. Under the hood, Omnismith exposes structured REST endpoints to register templates and attributes dynamically at runtime.

In a traditional development cycle, creating this cold-chain fleet management schema requires sequentially executing a series of dependent API requests.

1. Creating the Templates

First, the developer must register empty template containers for each operational concept:

POST /v1/templates HTTP/1.1
Host: api.omnismith.io
Content-Type: application/json
Authorization: Bearer <token>

{
  "name": "Vehicle",
  "description": "Fleet assets equipped with environmental sensors"
}

This returns a template identifier (e.g., 019f51bf-366c-72b9-94e1-0435af01e34a), which must be recorded to associate attributes in subsequent steps.

2. Registering Attributes

Next, individual attributes must be registered and attached to their templates. For instance, creating the high-frequency environmental telemetry attribute Temperature requires specifying its metric type and numerical data type:

POST /v1/attributes HTTP/1.1
Host: api.omnismith.io
Content-Type: application/json
Authorization: Bearer <token>

{
  "name": "Temperature",
  "attribute_type": 1,
  "data_type": 1,
  "template_ids": ["019f51bf-366c-72b9-94e1-0435af01e34a"]
}

3. Establishing References

Finally, the developer must configure relational integrity for reference fields—such as linking a shipment to its assigned driver—by updating the reference configuration on the respective attribute:

PUT /v1/attributes/019f51bf-3a42-71a3-95db-3736a6ad980b/reference HTTP/1.1
Host: api.omnismith.io
Content-Type: application/json
Authorization: Bearer <token>

{
  "target_template_id": "019f51bf-3836-71a9-a8d7-d5365ee60f3d",
  "target_attribute_id": "019f51bf-373f-714f-a811-7d983da1206f"
}

While these endpoints offer complete control, building a full relational schema manually requires tracking numerous UUID dependencies and drafting boilerplate payloads.

Scaffolding Business Domain Models with Dynamic Schemas

HomelessCoder — Sun, 12 Jul 2026 19:40:09 +0000

This article kicks off our new "Core Platform Capabilities" series

Operational platforms require structured data, but rigid database schemas slow down development. Omnismith uses a runtime EAV model to let schemas evolve alongside the business.

Operational platforms require structured data to track physical assets, inventory, or internal resources. Traditional relational databases mandate rigid schema definitions. Altering these schemas to accommodate new business requirements introduces migration files, application deployments, and potential database downtime.

Omnismith resolves this constraint by implementing a dynamic schema architecture based on the Entity-Attribute-Value (EAV) model. This structure permits runtime modifications to the domain model without altering the underlying database tables.

The Three Foundational Components

The platform divides domain modeling into three foundational components: Attributes, Templates, and Entities.

Attributes function as field definitions. They enforce data types and structural constraints. An attribute can be configured as a dimension (representing structural properties like strings, booleans, or dates), a metric (recording time-series values), a list (providing enumerated options), or a reference (linking to other entities).
Templates act as reusable schemas. A template groups specific attributes to define the shape of a business object. For example, a template representing server infrastructure might group a hostname string attribute, an environment list attribute, and a CPU utilization metric attribute.
Entities are the instantiated records. Every entity belongs to a template and populates the predefined attributes with explicit values.

Querying and Performance Tradeoffs

This architecture introduces a specific tradeoff. Querying an EAV structure requires more complex SQL operations than querying a flat relational table. Omnismith manages this complexity internally, exposing a unified entity search interface that supports filtering, sorting, and pagination without exposing the underlying table structure to the user.

Runtime Schema Evolution

The resulting system allows users to define custom business domains, group properties into templates, and deploy them to active projects instantly. Data structures are modeled and populated entirely at runtime, allowing the data model to evolve alongside the business.

Self-Hosting Prometheus and Grafana for Omnismith (For Now)

HomelessCoder — Sun, 28 Jun 2026 16:05:51 +0000

When building a data-intensive platform, real operational visibility becomes necessary quickly. A core API might be fast, but if event consumers lag or the database strains, the system degrades.

The industry reflex is often to reach for a managed SaaS provider or immediately start instrumenting the codebase with OpenTelemetry. But for an early-to-mid-stage project, SaaS ingest pricing can rapidly drain a budget, and app-level instrumentation can be a distraction when basic infrastructure baselines do not yet exist.

A pragmatic, battle-tested standard provides a solution: a self-hosted stack using Prometheus, Grafana, and dedicated Exporters.

Here is a look at the architecture, the tradeoffs, and why this is the right "Phase 1" approach for scaling platforms.

Observing Infrastructure Directly

Before instrumenting application-level spans and traces, a platform first needs a bedrock of infrastructure visibility. By starting with the underlying state and event layers (PostgreSQL and Kafka), a decoupled pipeline for system health is established.

Omnismith relies on robust foundational infrastructure. This separation of concerns keeps the application fast and reliable, but it introduces operational complexity. If the database experiences heavy query load or if Kafka consumers fall behind, the platform's performance degrades.

By collecting metrics directly from the infrastructure itself using postgres-exporter and kafka-exporter, a baseline of operational health is established that complements future application-level telemetry.

Architecture and Extensibility

By combining Prometheus with dedicated infrastructure exporters, robust telemetry is achieved without adding latency to the primary request path or polluting the application domain.

+------------------+                         +------------------+
|    PostgreSQL    |                         |   Apache Kafka   |
|    (Database)    |                         |    (Event Bus)   |
+------------------+                         +------------------+
          |                                            |
          v                                            v
+------------------+                         +------------------+
|     Postgres     |                         |       Kafka      |
|     Exporter     |                         |      Exporter    |
+------------------+                         +------------------+
          |                                            |
          |           +------------------+             |
          +---------> |    Prometheus    | <-----------+
                      | (Scrape & Alert) | 
                      +------------------+
                                |
                                v
                      +------------------+
                      |     Grafana      |
                      |   (Dashboards)   |
                      +------------------+

Each component fulfills a specific operational boundary:

Exporters: Run alongside the core infrastructure, exposing internal metrics (e.g., table sizes, partition counts, consumer group lag) over HTTP.
Prometheus: Periodically scrapes these exporters, maintains time-series data, and evaluates recording rules to trigger alerts.
Alerting & Visualization: Alerts are routed to communication channels via Grafana Alerting to avoid active dashboard monitoring. Grafana also queries Prometheus to provide unified, real-time visualization.

This design is highly extensible. As infrastructure complexity grows, additional metrics can be collected by simply provisioning new exporters and adding them as Prometheus scrape targets.

The TCO Tradeoff: Financial Efficiency vs. Maintenance

In the early and growth phases of a platform, infrastructure decisions require a balance between operational capability and financial discipline.

Deploying and managing a self-hosted observability stack rather than relying immediately on managed cloud SaaS providers yields two major advantages:

1. Direct Financial Efficiency

Managed monitoring solutions often carry steep pricing structures linked to ingested data volume.

While self-hosting requires engineering time to maintain, avoiding the steep data-ingest pricing drastically reduces direct cash burn in the early stages. Accepting the trade-off that self-hosting a stateful time-series database introduces its own maintenance burden (such as managing storage retention) is necessary. However, at current platform volumes, the financial savings vastly outweigh the operational overhead, directly extending runway.

2. Deep Platform Understanding

Operating complex distributed infrastructure hands-on builds essential domain expertise.

Configuring Prometheus scrape intervals, understanding exporter metrics, and provisioning Grafana dashboards provides deep visibility into low-level system mechanics. When the platform eventually scales to warrant managed cloud instances (such as AWS Managed Prometheus), the transition can be executed efficiently with an exact understanding of system requirements.

Conclusion

By monitoring the foundational infrastructure directly and operating an efficient self-hosted stack, the platform gains an extensible observability layer and significant cost savings during a critical growth phase. Application instrumentation is definitely next, but this infrastructure baseline had to come first.

Building a Blueprint Marketplace for Reusable Project Structures

HomelessCoder — Tue, 07 Apr 2026 21:07:20 +0000

Flexible platforms create repeated modeling work.

I saw that clearly while building Omnismith. Users can model their own business domains with templates, attributes, references, and entities. Many of those domains still start from similar structures.

Product catalogs, asset tracking, server monitoring, and CRM-style workflows use different labels and fields. They still reuse many of the same structural ideas.

That observation led to the Blueprint Marketplace.

Repeated domain work

Flexible platforms give users room to model their own systems. They also push a lot of design work onto each new workspace.

When the same structures are rebuilt in one workspace after another, that is repeated setup cost.

It also keeps useful ideas trapped inside isolated projects.

If one team has already designed a strong starting structure for a product catalog, a monitoring workspace, or a roadmap tracker, the product should make that reusable. Otherwise every new project starts by rediscovering work that was already done.

Omnismith needed a way to turn repeated domain modeling into reusable project structures.

Why "Template Marketplace" was not enough

The first internal name for this was Template Marketplace.

The name was too narrow.

A template is only one piece of what makes a project usable. A real starting point usually includes several templates, multiple attributes, references between models, and a set of decisions about how those pieces fit together. Publishing templates alone would expose fragments. I needed a way to package and publish a coherent project structure.

That is why the concept became Blueprint Marketplace.

The term “blueprint” covered the larger unit more accurately. It described a reusable structure that could be installed into another project and still make sense.

The publication boundary mattered early

The most important constraint was safety.

I wanted users to publish reusable structures. I also needed a clear guarantee that the marketplace would not expose actual project records.

That boundary shaped the model early.

User-published blueprints carry reusable definitions. They do not carry live business data. Featured blueprints are curated and reviewed before they appear in onboarding or other product-controlled surfaces.

That distinction made the marketplace usable as both a user-facing feature and an internal product distribution channel.

The implementation started from an existing example

The Product Catalog dataset had already been written in code with reuse in mind.

That reduced the amount of conceptual redesign. The real work was everything around it: persistence, publication flow, API support, and UI support.

I started with console support because it was the fastest way to exercise the publishing model and test the rules around what a blueprint could contain. That gave the rest of the implementation a clearer contract.

Why this changes the product

The Blueprint Marketplace changes how Omnismith can evolve as a platform.

reusable structures can be installed into new projects
useful domain knowledge becomes portable inside the product
curated official blueprints can guide important product flows
onboarding and starter experiences can reuse the same underlying publication system

Once reusable blueprints exist as a first-class capability, onboarding does not need to depend on special-case demo logic forever. The same system that supports marketplace publishing can also support official starter projects and curated first-session paths.

Final thought

The Blueprint Marketplace started from a simple product observation: flexible platforms still accumulate repeated domain work.

I did not want Omnismith users to keep rebuilding the same project structures in isolation. I wanted those structures to become publishable, installable, and reusable inside the product itself.

That made the marketplace worth building on its own. It also created the foundation for the onboarding work that came after it.

Designing Onboarding for a Flexible Data Platform

HomelessCoder — Sat, 21 Mar 2026 09:00:00 +0000

Flexible data products have a predictable onboarding problem. The empty state is technically correct. It also hides the product model.

That was the issue in Omnismith's original onboarding flow. New users were shown the interface, then dropped into a project with no templates, no attributes, and no entities. The tutorial explained the controls, but it did not show how a real workspace should be structured.

Users could follow individual actions. They still lacked a working mental model of the product.

The blank-canvas problem

Omnismith is flexible by design. Users define templates, attributes, references, and entities to fit their own domain.

That flexibility creates a cost during the first session. A new user has to understand both the interface and the shape of a finished system.

The original onboarding handled the first part and missed the second.

A flexible product is easier to understand when users can inspect a coherent example. Omnismith's onboarding gap came from missing context around the model and the workspace structure.

What the first session needed

The onboarding flow needed to expose the model immediately.

That meant starting with a project that contained:

a concrete schema
example records
visible relationships between records
enough structure to make browsing and editing feel like real work

The example also needed to stay small and coherent while still showing how the parts fit together.

The first redesign: a seeded demo project

The first redesign used a seeded Product Catalog project.

The dataset was intentionally small, but structurally complete enough to teach the model:

3 templates: Category, Brand, Product
11 attributes across those templates
shared fields such as Name and Description
references from Product to Category and Brand
a self-reference for related products
19 sample entities with realistic values

This was enough to make the system legible. A user could open the project and immediately see that templates define structure, entities hold values, and references connect records into something closer to a real application than an empty workspace does.

That scope was deliberate. The dataset's job was to make the product model visible within the first few minutes.

Why the guided tour still mattered

The demo project provided context, and the guided tour directed attention.

Users had a concrete workspace to inspect, and the tour moved them through the important surfaces in the right order.

Together, they reduced the time between first login and first useful understanding.

What this solved, and what it did not

This redesign fixed the immediate blank-canvas failure. New users no longer had to infer the product model from an empty screen.

It did not solve every onboarding problem.

One seeded dataset is still one opinionated starting point. It helps users understand the system, but it also assumes that one example should be relevant to everyone. That later became the next onboarding problem to solve.

Conclusion

For flexible products, an empty workspace is a poor first lesson.

Omnismith became easier to understand after onboarding began with a small working system. Clear visibility into the product model improved first-session comprehension.

That was the first onboarding redesign. The next question was how to keep that clarity without forcing every user into the same example.

Why Omnismith Uses Flexible Schema for Operational Data

HomelessCoder — Thu, 19 Mar 2026 07:30:00 +0000

Omnismith was built around a simple constraint: many operational systems need different schemas, but the same platform capabilities.

Many operational systems have different schemas but the same platform requirements.

A product catalog needs categories, brands, and products. An infrastructure workspace needs servers, services, incidents, and metrics. An IT asset system needs contracts, devices, licenses, and owners.

The fields are different. The surrounding platform needs are usually the same.

You still need structured records, permissions, history, dashboards, imports, API access, and, in some cases, time-series data.

That is the problem Omnismith was built to address.

The Repeated Problem

The core issue is not that teams need databases. The issue is that they repeatedly need systems built around different data models while the surrounding platform requirements stay mostly stable.

The implementation pattern is familiar:

define a schema
build CRUD screens
add permissions
add history
add imports and exports
add charts or reporting
expose the result through an API

That work is manageable when the schema is stable and the system is narrow.

It becomes expensive when the structure changes often or when the same product needs to support several operational domains. In those cases, too much work goes into rebuilding the platform around the schema instead of working on the domain itself.

This is common in internal tools, operational backoffice systems, monitoring workspaces, and domain-specific SaaS products. The schema changes with the business model, but the surrounding platform needs remain familiar.

Why Flexible Schema Is The Core Model

Omnismith uses an Entity-Attribute-Value model so the structure itself can be managed as data.

In practical terms:

attributes define fields
templates define structure
entities store actual records

That allows a workspace to define its own schema without requiring code changes for every new field or template.

If a team needs a Server template with hostname, CPU cores, environment, and owner, that structure can be created directly in the product. If another team needs Supplier, Contract, and Renewal Date, it can define a different model in the same system.

The point is not schema flexibility for its own sake. The point is to reduce the cost of building and maintaining operational systems whose structure changes over time.

This changes the development boundary. Instead of treating every schema adjustment as an application change, the product can treat structure as workspace data and handle the surrounding operational behavior in a consistent way.

Why Dynamic Schema Alone Is Not Enough

Flexible schema alone is not enough for the types of systems Omnismith is meant to support.

Operational data usually needs more than field definition and record editing.

It also needs:

history, so changes are traceable
role-based access control, so access is scoped properly
API-first access, so the workspace can be integrated into other systems
time-series support, so metrics can be attached to entities instead of stored somewhere else

That combination defines the actual product boundary.

Omnismith is meant for systems where the schema is flexible, but auditability and operational visibility still matter.

That is also why the product is opinionated in a few specific directions. Changes are tracked. Access is scoped. API access is a first-class interface rather than an afterthought. Metrics can be stored against the same entities that define the operational model.

A server, sensor, contract, or product record does not need a separate system just because one part of its state changes over time.

Example Use Cases

This model fits several kinds of structured operational work particularly well:

IT asset management
server and service monitoring
product and catalog management
consent and compliance tracking
internal backoffice systems with changing data models

The common pattern is not the domain itself. The common pattern is that each use case needs structured records together with operational behavior around those records.

An IT asset workspace needs devices, owners, contracts, warranties, and licenses. A monitoring workspace needs services, incidents, servers, and metric history. A catalog needs products, categories, pricing, stock state, and references. These are different models, but they benefit from the same platform shape.

Scope

Omnismith is not trying to be a universal replacement for every spreadsheet or content tool.

The intended scope is narrower and more practical: structured operational data that changes over time, needs clear access control, and benefits from being exposed through an API.

That is why flexible schema is combined with time-series support, full history, dashboards, RBAC, and API-driven workflows. Those capabilities make the schema model useful in day-to-day operation rather than only convenient during setup.

Conclusion

Omnismith was built for teams that need to model structured operational data without rebuilding the surrounding platform every time the schema changes.

Flexible schema is the core mechanism. History, permissions, API access, and time-series support are what make that mechanism useful in practice.

That is the product boundary: not only storing custom fields, but supporting the operational systems built on top of them.

Building ng-beacon: a lightweight guided tour library for Angular

HomelessCoder — Wed, 11 Mar 2026 08:17:00 +0000

I was working on Omnismith and needed a decent product tour. That sounded like a solved problem, so I went looking for an Angular package I could install and forget about.

There were usable options. Some were solid. But none fit the shape I wanted for this app: no manual scripts or stylesheets, no generic abstraction I had to translate back into Angular, and nothing that felt awkward in a zoneless Signals-based app.

So I built one.

It's called ng-beacon: a lightweight guided tour library for Angular 19+, built around Signals, SVG spotlight overlays, and a deliberately small setup.

This post is less about “I published a package” and more about the constraints that shaped it, which parts turned out to matter, and how the API changed once it had to survive real application code.

The Constraint Was Simplicity

I didn't want a tour system that became its own mini-framework. I wanted something that looked roughly like this:

provideBeacon()

and later:

this.beaconService.start(STEPS)

That was the baseline: no Angular Material dependency, no CDK requirement, no big configuration surface, no assumptions about which translation library a consumer uses, and no architectural gravity that would make the feature feel more expensive than it should.

There are good generic tour libraries. I just didn't want to adapt a generic engine into Angular-shaped application code if I could avoid it. That constraint ended up shaping almost every decision.

The Parts That Were Actually Fun to Build

https://github.com/HomelessCoder/ng-beacon | Demo GIF

I started with an SVG spotlight overlay because it gave me clean geometry and smooth control over the cutout. That part worked early. The more interesting problems were everything around it.

1. Click blocking around the spotlight

The SVG handled the visual spotlight nicely, but I still wanted the interaction model to be explicit.

The highlighted area may need to stay interactive while the rest of the screen still behaves like an overlay. I could have pushed all of that into the SVG layer, but I preferred to separate the visual layer from the interaction layer.

So I used dynamic click-blocking divs around the spotlight rectangle. Instead of one full-screen blocker doing everything, the page gets four blocker regions around the highlighted area.

It is not the only way to solve it, but it made pointer behavior much more explicit and predictable.

2. Tooltip positioning that reacts to real size

The tooltip height changes from step to step. Position changes too. Which means you can't just hardcode offsets and hope for the best.

So the positioning logic measures the tooltip, calculates where it wants to be, and then clamps it to the viewport edges. That sounds small on paper, but it is the difference between “works in the demo” and “feels stable while resizing the window and moving between steps.”

3. Iterating on the motion until it stopped feeling mechanical

I also spent time on the transitions. Nothing dramatic. Just enough to make the spotlight, blockers, and tooltip move like they belong to the same system instead of three separate UI layers reacting independently.

That polish mattered more than I expected.

The First API Was Too Simple

My first API was basically this:

start(steps: BeaconStep[])

And for simple cases, that is still fine. But real application code pushed it pretty quickly. Some tour steps only make sense while a specific component exists, so the library needed a way for components to contribute their own steps instead of keeping everything in one central list.

That led to registerTourSteps() and, from there, to startContextTour().

private readonly _tour = registerTourSteps(DASHBOARD_STEPS);

this.beaconService.startContextTour();

At that point the API made more sense. Components owned their local tour context, and the running tour could stay aligned with the actual UI. If a component disappeared during navigation, its steps disappeared with it.

start(steps) stayed as the simple option. startContextTour() became the better option for tours that need to follow real application state.

Internationalization Without Coupling

Omnismith supports eight languages, so I knew very early that hardcoded English strings inside the tour UI were not going to survive long.

At the same time, I didn't want the library coupled to a specific translation library.

In Omnismith I use ngx-translate. Someone else might use Transloco. Someone else might want their own function. So instead of picking a winner, I exposed a helper:

provideBeaconTranslateFn(() => {
  const translate = inject(TranslateService);
  return (key: string) => translate.instant(key);
})

That handles both step content and built-in UI labels like close / next / previous. Consumers get flexibility without the package forcing one i18n stack on them.

Tests Helped Me Stop Guessing

I added tests with AI assistance. What mattered was covering the behavior that was easy to break while iterating:

step filtering
navigation behavior
focus movement and restoration
overlay rendering
tooltip positioning branches
label translation and configuration

Once those were in place, I could keep refining the code without mentally re-running the same manual checks every time.

What the Final Result Looks Like

The setup stayed small, which was the whole point.

import { provideBeacon } from 'ng-beacon';

export const appConfig = {
  providers: [provideBeacon()],
};

@if (beaconService.isActive()) {
  <beacon-overlay />
}

// Direct tour
this.beaconService.start(MY_TOUR);

// Component-scoped tour
this.beaconService.startContextTour();

And if you need the more structured path, that is there too with registerTourSteps, startContextTour, and provideBeaconTranslateFn.

It also has two small lifecycle events now, finished and dismissed, which turned out to be useful for simple tracking and analytics.

That mattered to me more than I expected. I didn't just want a tour overlay. I wanted something that fit naturally into Angular application code, including translation, component ownership, reactive lifecycle handling, and app-level integration points.

That was the real target from the start: simple by default, but not boxed in.

A Few Things I Learned

Small libraries need stronger constraints, not fewer. If you don't decide what to exclude, they become messy surprisingly fast.

The API you start with is rarely the API you actually need. start(BeaconStep[]) was fine until the app got bigger, tour context became local, and components started destroying themselves mid-tour.

Framework-agnostic integration points are usually worth it. The translation hook is a good example. Coupling would have been easier in the short term and worse for everyone else.

Polish matters more than feature count for UI infrastructure. Smooth motion, stable positioning, and clean focus behavior are what make a tour feel trustworthy.

If you're building Angular apps and want something that feels more native to Angular application structure than a generic wrapper, maybe this is useful.

This is my first public TypeScript / Angular library, which makes it more significant to me than a normal internal extraction. Not because it's a giant technical achievement. Just because shipping a public package feels different. It's one thing to write code for your own app. It's another to write something other people might install and judge in five minutes.

If nothing else, building it reminded me that sometimes the right answer to “surely a package already exists for this” is “yes, but not one I actually want to use.”

👉 npm: ng-beacon
👉 GitHub: HomelessCoder/ng-beacon

If you try it and something feels awkward, I'd genuinely rather hear that than a polite “looks nice.” That's the only way these packages get better.

From an Unemployed Side-Project to AWS Community Builder: Why you should start sharing today

HomelessCoder — Wed, 04 Mar 2026 10:23:36 +0000

Six months ago I was unemployed. I was also nervous, uncertain, and had never "built in public" in my life.

Yesterday, I received an email confirming that I've been accepted into the AWS Community Builders program for 2026-2027.

I'm writing this because I want to talk to the version of myself from six months ago - the one who was (and still is!) hesitant to hit "Publish" on that first post.

How it started

When I found myself between jobs, I decided to pour my energy into an open-source project: a PHP modular framework. I had a specific vision for modular monolith architecture and willingness to share it with the PHP community. I started writing here on dev.to to document the "why" and the "how": Building a Modular PHP Paradigm Series' Articles

At the time, I didn't think of myself as a "writer" or a "content creator". I was just a dev with an idea.

The Turning Point

Sharing my work was not just about the code. It was about building confidence, engaging with the community, and developing the idea with insights that were not on my radar before. It led to a very unexpected, yet rewarding outcome: my acceptance into the AWS Community Builders program.

My message to you

If you are working on something, even if it feels niche, even if you think "no one will care": Share it anyway.

You don't just build software when you build in public; you are developing yourself. You build a reputation, a network, and opportunities that you can't even see yet.

I'm so proud to join this cohort, and I'm incredibly grateful to the dev.to community for being the place where this journey actually began.

Such an exciting moment!

I Launched. Users Showed Up. And Then I Watched Them Get Lost.

HomelessCoder — Tue, 24 Feb 2026 07:46:54 +0000

This is the original founder-side version of the story. From post 3 onward, the series was rewritten in a calmer, more technical style.

The first post in this series was about why Omnismith exists. This one is about what happened after I launched it.

The Parts Nobody Sees on the Commit Graph

I've been a software engineer for a long time. What I had never done was build a complete commercial product from zero — alone — with real money and real legal obligations on the line.

Some of what that actually involved:

Two full architectural iterations. The first codebase went in a direction I wasn't satisfied with. I scrapped it and started over with a modular monolith on my own framework, DDD, and hexagonal/use-case architecture. It was the right call — the backend genuinely became enjoyable to work in, not something to fight against.

Opening a legal entity while in immigration. I'm not an EU citizen. I opened a UK LTD — something I'd never done in my life, in a country that isn't mine, in a second language. It's surprisingly straightforward once you start, but it took mental energy I hadn't budgeted for.

Pricing based on actual economics. Not "what sounds reasonable" but walking through unit cost, comparable tools, where the free tier lines make sense, and why flat pricing over per-seat billing fits the developer audience I'm building for. That analysis took longer than I expected and I'm glad I didn't rush it.

A full DevOps pipeline, built and maintained by me. GitHub CI/CD, my own Kubernetes cluster, ArgoCD for GitOps deployments. I'm the infrastructure team. I'm also the backend. I'm also the frontend. I'm also the support desk.

Nobody helped me build any of this. I'm not complaining — it's genuinely something I'm proud of, even though bragging isn't really my thing. I'm writing it down because I think solo builders often undersell how much ground they're covering.

The First Registrations

After the soft launch, a small group of closed beta testers — people I actually know and trust — tried the early version and gave honest feedback. They caught small things I'd stopped seeing — a missing translation here, a confusing label there. They pointed at specific moments where they got confused. They told me the onboarding wasn't landing.

That feedback was more valuable than months of me staring at my own code. I'm genuinely grateful for it.

And then real users — people I don't know — started showing up. Each one felt way more significant than it probably should have. After years as a hired engineer building things for other people's products, seeing a real stranger's account appear in my system landed differently. It still does.

The Blank Canvas Problem

Here's what the beta feedback actually taught me.

Omnismith's v1 onboarding worked like this: register → step through a tutorial → land in an empty project with nothing in it — no templates, no attributes, no data.

I thought that was fine. The tutorial explained the concepts. The user had a clean slate to start.

What actually happened: users finished the tutorial and then stared at an empty screen, having memorized a sequence of UI steps but with no immediate sense of what to actually do with them. The mental model wasn't formed yet. And blank canvases are paralyzing — they're for people who already know what they want to paint.

v2 is different. Now when you register, you don't get an empty project. You get a demo project pre-populated with a real dataset: a product catalog.

It has 3 templates — Category, Brand, and Product — with 11 attributes across them. Some attributes are shared across templates (Name, Description). The Product template uses References to link each product to its Category and Brand, and even has a self-referencing "Related Product" link. There are 19 sample entities: 4 categories (Electronics, Furniture, Apparel, Books), 5 brands, and 10 products with real prices, stock status, release dates, and tags.

It's not a lot. But it's enough to instantly understand the shape of the platform. There's something to click on. There's data to edit. The templates tell you "this is how structure works." The entities tell you "this is what your data looks like."

On top of that, I added an interactive tour — something in the spirit of Intro.js — that walks you through the actual UI with contextual pointers. Not a wall of text in a help doc, but a live guide that highlights the element you're looking at right now. That combination — real data you can touch plus a tour that shows you where to look — landed much better than v1's tutorial-then-empty-canvas approach.

My beta testers stopped asking "what do I do now?" Which was the only metric that mattered.

The Lesson That Should Have Been Obvious

The blank canvas problem is not new. Every tool with a new user flow has solved or failed to solve it. But when it's your tool, your mental model of it is so complete that you forget how much context you're carrying that your user doesn't have yet.

You see a blank project and feel possibilities. Your user sees nothing.

Show them a story they can edit. Don't make them write the opening chapter.

That was probably the most valuable lesson of my early founder days. Not a technical insight. Not an architecture decision. A UX realization delivered by real people being kind enough to tell me where they got stuck instead of just quietly leaving.

If you're building a tool and your new user flow ends with "and now they have a blank canvas" — reconsider that.

👉 omnismith.io — log in and see the demo project yourself
👉 app.omnismith.io — free tier, no credit card
👉 docs.omnismith.io — now actually worth reading

Part of the "I'm Building Omnismith in Public" series. Previous: I Built This Because I Was Tired of Building Admin Panels.

I Built This Because I Was Tired of Building Admin Panels

HomelessCoder — Mon, 16 Feb 2026 20:29:41 +0000

This is the original founder-side version of the story. From post 3 onward, the series was rewritten in a calmer, more technical style.

It's Feb 16, 2026, and I'm doing something that feels both exciting and terrifying: I'm opening Omnismith to the public. After several months of development, the landing page is live, payments are integrated, the app works. This is the moment.

But let me back up and tell you why this exists.

The Problem I Kept Running Into

If you've worked as a developer-for-hire or in an agency, you know this pattern by heart:

Client needs an admin panel
You build it (again)
"Can we add a field for X?"
You write a migration, update the model, modify the form
"Actually, can we track Y over time?"
You add TimescaleDB, write aggregation queries, build charts
"Who changed this value last week?"
You implement audit logging
Repeat for the next 15 clients

Every project had the same base requirements, just different data structures. CRM for one client, inventory management for another, server monitoring for a third. Same features (CRUD, history, charts, access control), different schemas.

At some point, I got tired of it.

The EAV Realization

I started thinking: what if the structure itself was data?

This led me to Entity-Attribute-Value (EAV) architecture. Instead of hardcoding schemas in migrations, you define them in the UI:

Attributes are your building blocks (like table columns)
Templates are your schemas (like table definitions)
Entities are your actual data (like table rows)

You want to track servers? Create attributes for Hostname, IP Address, CPU Cores, Memory GB. Combine them into a "Server" template. Done. No migration files. No deployment. No downtime.

You want to add OS version? Create the attribute, add it to the template. It's available immediately.

This isn't a new idea—Airtable does this beautifully, Notion databases do this, hell, even WordPress custom fields do a version of this. But I needed something that also handled:

Metric ingestion for time-series data (think Datadog, but for any entity)
Full audit history (who changed what, when, and why)
Proper RBAC (role-based + resource-level access control)
API-first architecture (with OpenAPI spec, ready for integrations)

So I built it. Using my own modular PHP framework (yes, the one I wrote about before), PostgreSQL with TimescaleDB for time-series, and Angular 21 for the UI.

What Makes This Different From Airtable

If you just need flexible schemas and basic CRUD, Airtable is fantastic. It's polished, has a great ecosystem, and works well for business teams. But here's what it doesn't do:

Time-series metric ingestion. Airtable stores snapshots—each record is a moment in time. Omnismith stores timelines. You can push metrics via API every 30 seconds (CPU usage, temperature, API request counts, sensor readings) and query them like: "Show me average CPU usage for the last 7 days." This isn't a workaround with linked records and formulas—it's TimescaleDB under the hood, built for this exact use case.

Full audit history without manual versioning. Every field change is logged automatically with who/what/when. No need to create separate "Version History" tables or complex automation rules to track changes.

AI that executes, not suggests. Airtable's AI generates formulas and field descriptions. Omnismith's AI creates templates, adds attributes, inserts entities, and queries your data. It has direct function-calling access to your database through the OpenAPI spec. It's not a documentation helper—it's a schema builder.

Flat pricing for developers. $99/month gets you 50,000 entities with all features unlocked. Airtable Team costs $20/seat, so 5 users = $100/month for 50K records—but you're locked into per-seat billing even if you're just using the API. Need RBAC? That's Business tier at $45/seat. Need audit logs? Same. Omnismith: everything's included.

API-first design. Full OpenAPI spec generated from code. Every UI action has an API equivalent. Built for developers who need programmatic control over their data platform, not just business users clicking through forms.

If Airtable is for marketing teams managing campaigns, Omnismith is for developers building IoT platforms, SaaS backends, or internal tools that need both flexible schemas and time-series analytics.

The AI Assistant That Actually Works

Here's where it gets interesting. I added an AI Assistant—but not the kind that gives you generic advice or writes code snippets. This one executes.

It's powered by Google Gemini 2.5 and has direct access to your Omnismith data through function calling. Watch what happens when you talk to it:

You: "Create a Server template with hostname, IP, OS, and CPU cores"

The assistant doesn't just tell you how to do it. It:

Creates a StringAttribute for "Hostname"
Creates a StringAttribute for "IP Address"
Creates a ListAttribute for "OS" with options like "Ubuntu", "CentOS", "Windows"
Creates a NumberAttribute for "CPU Cores"
Creates a Template called "Server"
Associates all 4 attributes with the template

You see all of this happen in real-time—streaming responses with visible tool execution.

You: "Add a new server called web-prod-01 with IP 10.0.1.50, Ubuntu, 8 cores"

It creates the entity, fills in all the attributes. Done.

You: "Show me all servers with more than 4 CPU cores"

It queries your data and returns the results in a readable format.

This isn't a chatbot that suggests changes. It's an agent that makes them. The LLM proxy layer (a custom Fastify server I built) handles streaming, tool orchestration, and authentication. The tools themselves are auto-generated from the OpenAPI spec. Everything is schema-aware.

For developers building systems for non-technical clients, this is huge. Your client can literally describe what they need in plain language, and the assistant scaffolds it. No training documentation, no "click here, then here, then submit" tutorials. Just conversation.

What You Can Actually Do With It

Right now, Omnismith is being used for:

Personal AI assistants (data from Telegram bots, reminder systems)
IoT device monitoring (temperature, humidity, motion sensors pushing metrics via API)
User consent tracking (GDPR compliance, versioned agreements)
Server fleet management (infrastructure inventory + metric dashboards)
Product catalogs (headless backend for custom storefronts)

The free tier gives you 150 entities and 7 days of history retention—enough to validate an idea or run a small personal project. The Scale tier ($99/month) gives you 50,000 entities, 180 days of retention, and all features unlocked: AI Assistant, full RBAC, audit logging, dashboards, automations—no per-seat charges, no premium tiers. (Compare: Airtable Team is $20/seat for similar record limits, but RBAC and audit logs require Business tier at $45/seat.)

Full OpenAPI spec, so you can integrate it with anything. I use it via API tokens from custom scripts. The UI is in 8 languages.

The Tech Stack (For the Curious)

Backend:

PHP 8.4 (strict types, readonly properties, enums, attributes)
Custom modular framework (explicit DI, hexagonal architecture, DDD)
PostgreSQL + TimescaleDB
Transactional outbox pattern for domain events
OpenAPI spec auto-generated from PHP attributes
PHPUnit: Tests: 996, Assertions: 5775

Frontend:

Angular 21 (zoneless, standalone components)
Angular Signals for state management
Angular Material + TailwindCSS
rxResource for data fetching
AG Charts for visualizations

AI Layer:

Custom LLM proxy (Fastify + TypeScript)
Google Gemini 2.5
Function calling with OpenAPI-derived tools
SSE streaming with visible tool execution

I've written about the framework before on dev.to (see my modular architecture series), and yes, Omnismith is built entirely on it. That's validation #1 that the architecture actually works at scale.

Current Focus & Roadmap

I'm building this in public and prioritizing core stability over "feature bloat". While it is in beta, I'm focused on perfecting the desktop experience and core data visualization:

Current Visuals: High-performance line charts, stats, gauges, and lists (Advanced chart types in development).
Workflow: Currently focused on core data-handling; a visual automation builder (aka "Business Processes") to trigger automated data updates on specific events is the next major milestone.
Mobile: Optimized for desktop power-users; responsive mobile tweaks are rolling out weekly, but it's already usable.

This isn't a "replace everything" tool yet - it's a lean, functional engine for users who need simplicity and effectiveness without the enterprise clutter. It's functional, tested, and solving real problems for the handful of users I've soft-launched with.

Why I'm Telling You This

I'm a developer. I know how to write code, architect systems, and ship products. What I don't know how to do is market things with loud, empty promises.

I'm not going to tell you Omnismith is "revolutionary" or "unprecedented" or will "transform your workflow." It's a tool. It solves a specific set of problems (flexible schemas + time-series + audit history) better than cobbling together Airtable + Datadog + custom code.

If you've ever built an admin panel and thought "there has to be a better way," this might be that way. If you need to track things (servers, products, sensors, contracts, whatever) and see how they change over time, this is built for that.

Try it. Break it. Tell me what's wrong. I'm listening.

👉 omnismith.io
👉 app.omnismith.io (150 entities free, no credit card)
👉 swagger.omnismith.io

P.S. The AI Assistant demo is real. Log in, hit the AI Assistant menu, and try: "Create a Product template with name, price, and SKU". Watch it work.

P.P.S. If you're curious about the modular framework powering all of this, I've written a series about it: Solving PHP's Module Coupling Problem.

Auto-Discovering Console Commands in Power Modules

HomelessCoder — Thu, 16 Oct 2025 00:05:33 +0000

A couple of days ago, I was working on a PHP project that uses the Power Modules framework and Symfony Console, and I realized I was repeating the same command registration pattern across multiple projects. Time to build something better!

For those new to the series: Power Modules is a modular PHP framework where each module encapsulates its own logic and dependencies, communicating through well-defined interfaces while maintaining strict boundaries.

I already had a working setup/boilerplate for registering console commands exported from a Power Module (using the ExportsComponents interface) that I copy-pasted across projects. It follows the Power Modules framework principles: keep modules encapsulated and their dependencies private, and delegate the instantiation and dependency resolution to their DI container:

$modules = [
    new OrdersModule(),
    new UsersModule(),
    // ... other modules
];
$app = new ModularAppBuilder(__DIR__ . '/../')
    ->withModules(...$modules)
    ->build()
;

$console = new \Symfony\Component\Console\Application('My Console Application', '0.1.0');

foreach ($modules as $module) {
    foreach ($module::exports() as $exportedComponent) {
        // $exportedComponent is just a class-string that references to a power module DI container
        if (is_a($exportedComponent, Command::class, true) === true) {
            $console->add($app->get($exportedComponent));
        }
    }
}

The Problem

This works, but it felt clunky repeating this boilerplate across projects. I knew that Symfony DI can manage console commands, and I wanted to see if I could build something that automatically discovers and registers console commands from different modules. So I thought: Why not apply the PowerModuleSetup concept for this? (you can read more about it here: The Night I Discovered I'd Built Something Revolutionary (And Didn't Know It)

Building the Solution

The implementation was quite straightforward - create a PowerModuleSetup that does the same thing as the above code, but in a more modular and reusable way.

First Iteration: Direct Registration

This PowerModuleSetup bridges Symfony Console with the Power Modules framework's modular architecture. Modules export console commands while maintaining encapsulation principles, and commands are auto-discovered and registered into a central Console\Application.

final class ConsoleCommandsSetup implements PowerModuleSetup
{
    private \Symfony\Component\Console\Application $console;

    public function __construct()
    {
        $this->console = new \Symfony\Component\Console\Application();
    }

    public function setup(PowerModuleSetupDto $dto): void
    {
        if (!$dto->powerModule instanceof ExportsComponents) {
            return;
        }

        if ($dto->setupPhase !== SetupPhase::Post) {
            return;
        }

        if ($dto->rootContainer->has(Application::class) === false) {
            $dto->rootContainer->set(Application::class, $this->console);
        }

        foreach ($dto->powerModule::exports() as $exportedComponent) {
            if (is_a($exportedComponent, Command::class, true) === true) {
                $this->console->add($dto->rootContainer->get($exportedComponent));
            }
        }
    }
}

Adding Lazy-Loading with ContainerCommandLoader

I wanted to take it further with deferred command instantiation. Symfony's ContainerCommandLoader loads commands from a DI container on-demand. Since ExportsComponentsSetup already registers exported components in the root container, I could leverage that. This meant updating the setup to use a two-phase approach: collect commands in the Pre phase and register them in the Post phase.

final class ConsoleCommandsSetup implements PowerModuleSetup
{
    private Application $console;
    private ?CommandLoaderInterface $commandLoader = null;

    /**
     * @var array<string,class-string<Command>> $commandMap
     */
    private array $commandMap = [];

    public function __construct()
    {
        $this->console = new Application();
    }

    public function setup(PowerModuleSetupDto $powerModuleSetupDto): void
    {
        if (!$powerModuleSetupDto->powerModule instanceof ExportsComponents) {
            return;
        }

        if ($powerModuleSetupDto->setupPhase === SetupPhase::Pre) {
            // PRE phase: collect all commands to be registered later
            foreach ($powerModuleSetupDto->powerModule::exports() as $component) {
                if (is_subclass_of($component, Command::class)) {
                    if ($attribute = (new ReflectionClass($component))->getAttributes(AsCommand::class)) {
                        $this->commandMap[$attribute[0]->newInstance()->name] = $component;
                    }
                }
            }

            return;
        }

        if ($this->commandLoader !== null) {
            return;
        }

        $this->commandLoader = new ContainerCommandLoader(
            $powerModuleSetupDto->rootContainer,
            $this->commandMap,
        );

        $console = $this->console;

        if ($powerModuleSetupDto->rootContainer->has(Application::class) === true) {
            $console = $powerModuleSetupDto->rootContainer->get(Application::class);
        } else {
            $powerModuleSetupDto->rootContainer->set(Application::class, $this->console);
        }

        $console->setCommandLoader($this->commandLoader);
    }
}

Usage

Now I have a reusable PowerModuleSetup that can be added to any Power Modules application to automatically discover and register console commands from modules:

$app = new ModularAppBuilder(__DIR__ . '/../')
    ->withModules(
        new OrdersModule(),
        new UsersModule(),
    )
    ->withPowerSetup(new ConsoleCommandsSetup())
    ->build();

// Console application is now available with all module commands registered
$console = $app->get(\Symfony\Component\Console\Application::class);
$console->run();

Wrapping Up

The complete implementation is available in the repository: power-modules/console

Install via Composer:

composer require power-modules/console

This pattern eliminated the boilerplate I was copy-pasting and made command registration automatic. If you're building modular applications with Power Modules, this setup might save you some time too.

From Vision to Visualization: Building Pluggable Architecture for PHP

HomelessCoder — Tue, 30 Sep 2025 18:24:49 +0000

The spark: from architecture to ecosystems 🔌

In my first post, I shared how explicit module boundaries (imports/exports) make architecture visible. In my second post, I realized that same foundation quietly unlocked an ecosystem pattern that goes beyond web apps.

This post shows the first concrete piece of that ecosystem story: a dependency‑injection‑native plugin system with static analysis support (Layer 1), a real extension point in the dependency graph module (Layer 2), and a third‑party implementation you can use today—the Mermaid renderers (Layer 3).

You'll see how plugins are discovered automatically, resolved with DI, and used to visualize your architecture with one command. This foundation enables everything from content filter pipelines to payment gateway adapters—patterns we'll explore in Part 2.

Ecosystem layers, now practical

Layer 1: Foundation for plugins (generic, domain‑agnostic)
Layer 2: Domain‑specific cores exposing plugin points (e.g., dependency‑graph → Renderer)
Layer 3: Third‑party plugins (e.g., Mermaid renderers)

We'll walk through all three, end‑to‑end.

Layer 1 — The plugin foundation (generic but powerful) 🧩

The goals:

Plugins are first‑class citizens with metadata
Registries provide IDE/static analysis support (via PHPDoc generics) and lazy loading (instantiate on demand)
Discovery is automatic at app boot, integrated with module isolation

Key pieces (power-modules/plugin):

Plugin: every plugin returns PluginMetadata
PluginRegistry<TPlugin>: register, list, and instantiate plugins (generic annotation for IDE support)
GenericPluginRegistry: default, DI‑native implementation
ProvidesPlugins<TPlugin>: a module declares its plugins for one or more registries
Setups:
- GenericPluginRegistrySetup: provides a default registry in root
- PluginRegistryModuleConvenienceSetup: makes the registry injectable in modules
- PluginRegistrySetup: discovers modules that implement ProvidesPlugins and registers their plugins

A tiny example:

use Modular\Framework\App\ModularAppBuilder;
use Modular\Framework\PowerModule\Contract\PowerModule;
use Modular\Framework\Container\ConfigurableContainerInterface;
use Modular\Plugin\Contract\Plugin;
use Modular\Plugin\PluginMetadata;
use Modular\Plugin\Contract\PluginRegistry;
use Modular\Plugin\Contract\ProvidesPlugins;
use Modular\Plugin\PowerModule\Setup\PluginRegistrySetup;

interface TextProcessor extends Plugin { public function process(string $in): string; }

final class UppercasePlugin implements TextProcessor
{
    public static function getPluginMetadata(): PluginMetadata
    {
        return new PluginMetadata('Uppercase', '1.0.0', 'Converts text to UPPERCASE');
    }
    public function process(string $in): string { return strtoupper($in); }
}

final class TextPluginModule implements PowerModule, ProvidesPlugins
{
    public static function getPlugins(): array
    {
        return [PluginRegistry::class => [UppercasePlugin::class]]; // declare plugins
    }

    public function register(ConfigurableContainerInterface $c): void
    {
        $c->set(UppercasePlugin::class, UppercasePlugin::class); // DI binding
    }
}

$app = (new ModularAppBuilder(__DIR__))
    ->withPowerSetup(...PluginRegistrySetup::withDefaults())
    ->withModules(TextPluginModule::class)
    ->build();

/** @var PluginRegistry<TextProcessor> $registry */
$registry = $app->get(PluginRegistry::class);
$plugin = $registry->makePlugin(UppercasePlugin::class);
echo $plugin->process('hello'); // HELLO

What's happening:

At boot, PluginRegistrySetup scans modules that implement ProvidesPlugins
For each plugin class, it registers a (class → owning container) mapping in the root registry
At runtime, makePlugin() resolves the instance from that module's container (full DI)

Layer 2 — The dependency graph exposes a plugin point 🧭

The power-modules/dependency-graph module collects your modules and their relationships during app bootstrap.

DependencyGraphSetup builds a DependencyGraph from ModuleNodes and their imports
Renderer is a plugin contract for turning that graph into outputs (text, JSON, Mermaid, etc.)
RendererPluginRegistry (extends GenericPluginRegistry<Renderer>) is exported by RendererModule

Interface:

interface Renderer extends Plugin
{
    public function render(DependencyGraph $graph): string;
    public function getFileExtension(): string; // e.g. mmd, json
    public function getMimeType(): string;
    public function getDescription(): string;
}

This gives us a clean "slot" where anyone can add a new renderer.

Layer 3 — Third‑party Mermaid renderers 🧪

Now here's where it gets interesting. This repository (power-modules/dependency-graph-mermaid) is a third‑party plugin package that extends the dependency-graph module with visual renderers.

The MermaidRendererModule registers three plugins implementing Renderer:

Flowchart: MermaidGraph (LR direction, shows imports as labeled arrows)
Class diagram: MermaidClassDiagram (TB direction + YAML frontmatter, exports as class members)
Timeline: MermaidTimeline (dependency levels as phases, Infrastructure/Domain sections)

They're regular plugins declared via ProvidesPlugins<Renderer> and discovered automatically—no special wiring needed.

Visual tour: your architecture, rendered

The best part? You get immediate visual feedback. Below are small, self‑contained Mermaid snippets inspired by the ecommerce example. You can paste them into Mermaid Live or VS Code's Mermaid preview to see them rendered.

1) Flowchart (modules and imports)

2) Class diagram (exports as members, imports as dashed deps)

3) Timeline (boot phases by dependency levels)

Tip: in code, MermaidTimeline computes phases Kahn‑style and separates Infrastructure/Domain with a simple classifier.

Complete setup pattern 🚀

Here's the complete setup pattern—replace the example modules with your own:

Add the necessary setups and modules:

DependencyGraphSetup() to collect the graph during app bootstrap
...PluginRegistrySetup::withDefaults() to enable plugin discovery
RendererModule to expose the RendererPluginRegistry
MermaidRendererModule to register the three Mermaid plugins

use Modular\Framework\App\ModularAppBuilder;
use Modular\DependencyGraph\PowerModule\Setup\DependencyGraphSetup;
use Modular\DependencyGraph\Renderer\RendererModule;
use Modular\DependencyGraph\Renderer\Mermaid\MermaidRendererModule;
use Modular\DependencyGraph\Graph\DependencyGraph;
use Modular\DependencyGraph\Renderer\RendererPluginRegistry;
use Modular\Plugin\PowerModule\Setup\PluginRegistrySetup;

$app = (new ModularAppBuilder(__DIR__))
    ->withPowerSetup(new DependencyGraphSetup())
    ->withPowerSetup(...PluginRegistrySetup::withDefaults())
    ->withModules(
        // your app modules
        App\User\UserModule::class,
        App\Product\ProductModule::class,
        App\Order\OrderModule::class,
        App\Payment\PaymentModule::class,
        App\Notification\NotificationModule::class,
        App\Database\DatabaseModule::class,
        // plugin point + plugins
        RendererModule::class,
        MermaidRendererModule::class,
    )
    ->build();

$graph = $app->get(DependencyGraph::class);
$renderers = $app->get(RendererPluginRegistry::class);

foreach ($renderers->getRegisteredPlugins() as $rendererClass) {
    $renderer = $renderers->makePlugin($rendererClass);
    $code = $renderer->render($graph);
    file_put_contents(__DIR__ . '/mermaid/out.' . $renderer->getFileExtension(), $code);
}

Want ready‑made scripts? Check out examples.

Why this matters (and how teams use it) 📌

For refactoring: Spot central "god" modules that import from everyone, or unused modules that export but no one imports.

For onboarding: Give new teammates a real map—not just "here's the codebase," but "here's how modules connect and what they export."

For architecture reviews: Validate intended boundaries before they calcify. Catch cycles early.

For documentation: Check in generated .mmd files alongside code. PRs that change module relationships show visual diffs.

For evolution planning: Identify natural seams for service extraction—modules with low in‑degree and clear export contracts are good candidates.

For CI guardrails: Add analyzers to fail builds on cycles or unexpected coupling.

Try it yourself

Foundation: composer require power-modules/plugin
Graph + plugin point: composer require power-modules/dependency-graph
Mermaid renderers: composer require power-modules/dependency-graph-mermaid

Then add the setups and modules as shown above, render, and paste the .mmd into Mermaid Live.

What's next 🔮

Part 2: Building your own plugin ecosystem

Custom registries with domain-specific validation (payment gateways, content filters)
Config-driven plugin pipelines (tenant-specific processing steps)
Metadata-driven admin UIs (plugin catalogs without instantiation)
Real patterns: CMS filters, discount strategies, ETL steps, gateway adapters

Resources

Framework: power-modules/framework
Plugin system: power-modules/plugin
Dependency graph: power-modules/dependency-graph
Mermaid renderers: power-modules/dependency-graph-mermaid
Try the examples: Clone the repository and run php examples/ecommerce/generate.php

I'm building this ecosystem in the open. If you try it, build a renderer, or have ideas for Part 2—drop a comment or connect with me!

What architectural challenges keep you up at night? Have you tried similar visualization approaches? 💬