DEV Community: HomelessCoder

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? 💬

The Night I Discovered I'd Built Something Revolutionary (And Didn't Know It)

HomelessCoder — Wed, 24 Sep 2025 18:12:52 +0000

"Oh Saint Cats. What Have I Done?" 🤯

It was 11:47 PM on a Tuesday. I was writing documentation for my PHP framework, exploring plugin architecture patterns, when it hit me like a freight train.

I stopped typing. Stared at my screen. And said out loud to my empty room:

"Oh Saint Cats. What have I done."

The Setup: What I Thought I Was Building

Just two days ago, I shared my journey of building a modular PHP framework during my career transition. Coming from network engineering, PHP and Angular development, I was frustrated by the implicit, conventional dependencies and weak module boundaries in PHP applications. Most frameworks rely on conventions for module interaction, which often leads to accidental coupling and hidden dependencies.

My goal was simple: bring explicit import/export contracts and true encapsulation to PHP web applications.

I built:

Module-scoped DI containers (each module isolated)
Explicit import/export contracts (dependencies visible in code)
PowerModuleSetup pattern (cross-cutting functionality without coupling)

I thought I was solving the architectural problems of web applications.

But I had underestimated the scale of the solution.

The Realization: From Decoupled to Universal

From the beginning, I designed the framework to be decoupled from any specific domain. I proved this concept by building the HTTP router as a completely separate, optional package. I knew this design made it flexible, and I had even documented use cases for web APIs and ETL pipelines.

But the true "aha!" moment came while documenting the PowerModuleSetup plugin system. I wasn't just looking at individual use cases anymore; I was looking at the universal pattern that connected them.

That's when the penny dropped. The realization wasn't that the core was free of web code... I knew that. It was that the combination of PowerModule isolation and the PowerModuleSetup extension mechanism created a repeatable, universal pattern for building entire, domain-specific ecosystems.

Connecting the Dots

My heart was racing. It wasn't a frantic brainstorm of new ideas; it was the sudden, shocking realization that my existing examples were not just disparate use cases. They were all instances of the same powerful, underlying pattern.

The Web API Use Case...

$webApp = new ModularAppBuilder(__DIR__)
    ->withModules(ApiCoreModule::class, UserModule::class)
    ->addPowerModuleSetup(new RoutingSetup()) // A web-specific setup
    ->build();

The ETL Pipeline Use Case...

$etlApp = new ModularAppBuilder(__DIR__)
    ->withModules(EtlCoreModule::class, CsvExtractorModule::class)
    ->addPowerModuleSetup(new PipelineSetup()) // An ETL-specific setup
    ->build();

A Potential CLI Tool Use Case...

$cliApp = new ModularAppBuilder(__DIR__)
    ->withModules(CliCoreModule::class, GitModule::class)
    ->addPowerModuleSetup(new CommandSetup()) // A CLI-specific setup
    ->build();

The same modular patterns worked for everything.

The Ecosystem Revelation

But it got bigger. Much bigger.

I realized I hadn't just built a framework. I had built a framework for building ecosystems.

Layer 1: Core Framework & Universal Extensions
- power-modules/framework: The core modular architecture.
- power-modules/plugin (coming soon): Generic infrastructure for building plugin systems.
Layer 2: Domain-Specific Plugin Systems
- power-cms/core: Provides the core interfaces and plugin registry for a CMS ecosystem.
- power-gateway/core: Provides the core for an API Gateway ecosystem.
- power-etl/core: Provides the core for an ETL pipeline ecosystem.
Layer 3: Third-Party Plugins
- power-cms/blog: A blog plugin for the CMS ecosystem.
- power-gateway/auth: An authentication plugin for the API Gateway ecosystem.
- power-etl/csv: A CSV processing plugin for the ETL ecosystem.

The same PowerModuleSetup pattern could enable plugin discovery across completely different domains.

The Validation Mission

By this point, it was 1:30 AM and I was buzzing with excitement and disbelief. But I needed validation. Was this really as innovative as it felt, or was I just having a late-night coding high?

I crafted a comprehensive research prompt and submitted it for independent analysis. The task: compare my framework's architectural patterns against every major solution in the PHP ecosystem and beyond.

The research covered:

Symfony's bundle system and compiled containers
Laravel's service providers and packages
WordPress's plugin architecture
Drupal's module system
OSGi (Java) for comparison with true modularity
Node.js module patterns

I wanted the brutal truth.

The Verdict: Revolutionary, Not Just Useful

After extensive analysis, the independent research concluded:

"The Modular Framework is a revolutionary and unique architecture in the PHP ecosystem."

The key findings:

Module-scoped DI containers are unique in PHP - no major framework provides true container isolation per module
Runtime-enforced import/export contracts are unprecedented - most frameworks rely on convention, not architectural enforcement
The PowerModuleSetup pattern enables ecosystem building - a novel approach to cross-cutting functionality

Not just useful. Not just an improvement. A genuine paradigm shift.

The Architectural Vision Document

To formalize these findings, I created an Architectural Vision Document that serves as a technical white paper, positioning the framework within the broader landscape of software architecture.

It compares the framework directly against established solutions and demonstrates why this approach represents a new paradigm for building complex, maintainable PHP systems.

What This Means for PHP Development

This discovery has massive implications:

For Large-Scale Applications

True encapsulation prevents architectural decay
Explicit dependencies make systems maintainable
Team scalability through isolated module ownership

For Ecosystem Building

Consistent plugin patterns across different domains
Universal extension mechanisms via PowerModuleSetup
Framework-agnostic approach to modularity

For Microservice Evolution

Natural service boundaries defined by modules
Clear extraction path from monolith to services
Contract-based communication ready for HTTP APIs

The Technical Reality

Let me be clear about what this is:

~1,600 lines of focused, well-tested core code
PHPStan level 8, comprehensive test coverage
Built on proven patterns from other ecosystems
MIT licensed, completely open source

It's not about creating the "next big framework" - it's about bringing architectural rigor to PHP that was previously unavailable.

Try the Revolution Yourself

composer require power-modules/framework

Basic Example:

class MyModule implements PowerModule, ExportsComponents
{
    public static function exports(): array
    {
        return [MyService::class];
    }

    public function register(ConfigurableContainerInterface $container): void
    {
        $container->set(MyService::class, MyService::class);
    }
}

$app = new ModularAppBuilder(__DIR__)
    ->withModules(MyModule::class)
    ->build();

$service = $app->get(MyService::class);

The Journey Continues

This discovery has completely changed my perspective on what I've built. What started as personal frustration with PHP architecture has become something that could influence how we build complex backend systems.

The next steps:

Building example ecosystems (CMS, ETL, CLI tools)
Creating plugin developer guides
Exploring interoperability patterns between ecosystems

Resources

GitHub: power-modules/framework
Architectural Vision: Technical white paper
Research Analysis: Original research prompt

The Lesson

Sometimes the most innovative solutions come from focusing intensely on problems you truly understand. You might think you're building one thing, only to discover you've created something much more significant.

That Tuesday night reminded me why I love programming: the moment when you realize you've built something that could change how people approach entire categories of problems.

What architectural challenges have been keeping you up at night? Have you had similar "aha!" moments in your development journey?

The discovery that a personal project has broader implications than you ever imagined is one of the most exhilarating experiences in software development. This is mine.

Solving PHP's Module Coupling Problem: A Journey Into Modular Architecture

HomelessCoder — Mon, 22 Sep 2025 19:30:17 +0000

How I Built a Modular PHP Framework and What I Learned About Architecture

The Problem That Kept Me Up at Night 😴

As a PHP developer with decades of experience, I've built my fair share of complex applications. But there was always one architectural problem that frustrated me:

Module boundaries in PHP applications are often invisible and easily broken.

Here's what I mean:

// This looks innocent enough...
class OrderService
{
    public function __construct(
        private UserService $userService,
        private PaymentService $paymentService,
        private InventoryService $inventory,
        private EmailService $emailService,
    ) {}
}

But what happens when:

Someone refactors UserService without knowing OrderService depends on it?
You want to test OrderService but need to mock 4 different modules?
You need to extract the Payment module into a microservice?
A new developer joins and can't tell what depends on what?

The dependencies are implicit and hidden. Your DI container knows about them, but your code doesn't make them explicit.

The Inspiration: Learning from Other Ecosystems 💡

Coming from a network engineering background and working with Angular on the frontend, I've seen how other ecosystems handle this:

Angular Modules

@NgModule({
  imports: [CommonModule, UserModule],     // Explicit imports
  exports: [OrderComponent, OrderService], // Explicit exports
  providers: [OrderService]                // Internal services
})
export class OrderModule { }

OSGi (Java)

// Bundle explicitly declares what it imports/exports
Import-Package: com.example.user.service
Export-Package: com.example.order.service

The pattern was clear: successful module systems make dependencies explicit.

My Solution: PowerModules Framework 🚀

I decided to bring these patterns to PHP. Here's what I built:

1. Each Module Gets Its Own DI Container

Instead of one global container, each module has its own isolated space:

class OrderModule implements PowerModule 
{
    public function register(ConfigurableContainerInterface $container): void 
    {
        // This container is ONLY for OrderModule
        $container->set(OrderService::class, OrderService::class);
        $container->set(OrderRepository::class, OrderRepository::class);
        // These services are private to this module by default
    }
}

2. Explicit Export Contracts

If you want to share a service, you must explicitly export it:

class UserModule implements PowerModule, ExportsComponents
{
    public static function exports(): array 
    {
        return [
            UserService::class,  // Only this is available to other modules
        ];
    }

    public function register(ConfigurableContainerInterface $container): void 
    {
        $container->set(UserService::class, UserService::class);
        $container->set(PasswordHasher::class, PasswordHasher::class); // Private!
    }
}

3. Explicit Import Contracts

If you want to use another module's service, you must explicitly import it:

class OrderModule implements PowerModule, ImportsComponents
{
    public static function imports(): array 
    {
        return [
            ImportItem::create(UserModule::class, UserService::class),
            ImportItem::create(PaymentModule::class, PaymentService::class),
        ];
    }

    public function register(ConfigurableContainerInterface $container): void 
    {
        // Now UserService and PaymentService are available for injection
        $container->set(OrderService::class, OrderService::class)
            ->addArguments([
                UserService::class,
                PaymentService::class,
            ]);
    }
}

The magic: Your dependencies are now visible in your code, not hidden in configuration files!

The PowerModuleSetup Pattern ⚡

Here's where it gets interesting. How do you add cross-cutting functionality (like routing, events, logging) to ALL modules without breaking encapsulation?

I created the PowerModuleSetup pattern:

class RoutingSetup implements PowerModuleSetup
{
    public function setup(PowerModuleSetupDto $dto): void 
    {
        // This runs for EVERY module during app building
        if ($dto->powerModule instanceof HasRoutes) {
            // Pull all routes defined in this module and register them with the router
            $this->registerRoutes($dto->powerModule, $dto->moduleContainer);
        }
    }
}

// Usage
$app = new ModularAppBuilder(__DIR__)
    ->withModules(UserModule::class, OrderModule::class)
    ->addPowerModuleSetup(new RoutingSetup())  // Extends ALL modules with HasRoutes interface
    ->build();

This pattern allows extensions to work across all modules while maintaining isolation. This's how the power-modules/router extension works, and it also forms the foundation for the framework's explicit export/import system. Both cross-cutting features and module relationships are enabled through PowerModuleSetup, ensuring encapsulation and visibility at the same time.

Building the App: The Fluent API 🏗️

Putting it all together:

$app = new ModularAppBuilder(__DIR__)
    ->withConfig(Config::forAppRoot(__DIR__))
    ->withModules(
        AuthModule::class,
        UserModule::class, 
        OrderModule::class,
        PaymentModule::class
    )
    ->addPowerModuleSetup(new RoutingSetup())
    ->addPowerModuleSetup(new EventSetup())
    ->build();

// Access any exported service
$orderService = $app->get(OrderService::class);

What I Learned Building This 🎓

1. Dependency Resolution is Complex

I had to implement topological sorting to handle module dependencies:

Build a dependency graph from import statements
Detect circular dependencies
Sort modules in the correct loading order
Cache the result for performance

2. Two-Phase Loading is Essential

Phase 1: Register all modules and collect exports
Phase 2: Resolve imports and apply PowerModuleSetup extensions

This ensures all exports are available before any imports try to resolve them.

3. Container Hierarchy Matters

Root Container
├── Module A Container (isolated)
├── Module B Container (isolated)
└── Exported Services (aliases to module containers)

Each module's container is completely isolated, but exported services are accessible through the root container.

4. Explicit is Better Than Implicit

The import/export contracts make your architecture visible:

New developers can see module relationships at a glance
Refactoring becomes safer with explicit dependencies
Testing becomes easier with clear boundaries

Real-World Impact 📊

Here's what this approach enables:

Better Team Scaling

// Team A owns AuthModule
class AuthModule implements ExportsComponents {
    public static function exports(): array {
        return [
            UserService::class,
            AuthMiddleware::class
        ];
    }
}

// Team B owns OrderModule  
class OrderModule implements ImportsComponents {
    public static function imports(): array {
        return [
            ImportItem::create(AuthModule::class, UserService::class),
        ];
    }
}

Teams can work independently with clear contracts between modules.

Easier Testing

// Test OrderModule in isolation
$testApp = new ModularAppBuilder(__DIR__)
    ->withModules(
        MockUserModule::class,  // Test double
        OrderModule::class      // Real implementation
    )
    ->build();

Microservice Evolution

// Today: Modular monolith
ImportItem::create(UserModule::class, UserService::class)

// Tomorrow: HTTP API call
ImportItem::create(UserApiModule::class, UserService::class)

The import/export contracts naturally become API contracts.

The Technical Details 🔧

Framework Stats:

~1,600 lines of core code
PHPStan level 8 (maximum static analysis)
PHP 8.4+ with strict types
Comprehensive test coverage
PSR-11 container interoperability
MIT licensed

Key Components:

PowerModule: Core module interface
ConfigurableContainer: Custom DI container with method chaining
ModularAppBuilder: Fluent app construction
PowerModuleSetup: Extension system
ImportItem: Dependency declaration

Comparison with Existing Solutions 🔍

vs Symfony Bundles

// Symfony (implicit dependencies in services.yaml)
class OrderController {
    // Dependencies configured in YAML, not visible in code
}

// PowerModules (explicit imports in code)  
class OrderModule implements ImportsComponents {
    public static function imports(): array {
        return [
            ImportItem::create(UserModule::class, UserService::class),
        ];
    }
}

vs Laravel Service Providers

// Laravel (shared container)
App::bind(OrderService::class, function($app) {
    return new OrderService($app->make(UserService::class));
});

// PowerModules (isolated containers)
$container->set(OrderService::class, OrderService::class)
    ->addArguments([UserService::class]); // Resolved from module's container

Try It Yourself 🚀

composer require power-modules/framework

Basic Example:

class MyModule implements PowerModule, ExportsComponents
{
    public static function exports(): array
    {
        return [MyService::class];
    }

    public function register(ConfigurableContainerInterface $container): void
    {
        $container->set(MyService::class, MyService::class);
    }
}

$app = new ModularAppBuilder(__DIR__)
    ->withModules(MyModule::class)
    ->build();

$service = $app->get(MyService::class);
// $service is ready to use, and IDE autocompletion works!

What's Next? 🔮

I'm working on:

power-modules/events: Event-driven architecture extension
Better documentation: More examples and patterns
Performance optimizations: Caching for module routes
... Suggestions welcome!

Conclusion 💭

Building this framework taught me more about dependency injection, module systems, and architectural patterns than years of just using existing tools.

Key takeaways:

Explicit dependencies are better than implicit ones
Module boundaries should be enforced, not just conventional
Cross-cutting concerns can be added without breaking encapsulation
Good architecture supports evolution (monolith → microservices)

Is it revolutionary? No - these patterns exist in other ecosystems.

Is it useful? I think so - it solves real problems I've faced in complex PHP applications.

Resources 📚

GitHub: power-modules/framework
Packagist: power-modules/framework
Router Extension: power-modules/router
Use Cases & Examples: Use Cases & Examples

What architectural challenges do you face in your PHP projects? Have you tried similar approaches? I'd love to hear your thoughts in the comments! 💬