A follow-up: how the architecture works
In my previous article, I explained why I built NGB Platform and what problem it is trying to solve:
I Built an Open-Source Platform Foundation for Accounting-Centric Business Apps
That article was mostly about the why.
Why generic web frameworks are not enough for serious business applications.
Why large ERP products solve many of the right problems, but often inside closed and complex product ecosystems.
And why I wanted to build an open-source platform foundation for accounting-centric business applications.
This article is the follow-up.
Instead of focusing on why NGB exists, I want to walk through how the architecture works:
- how documents represent business intent
- how posting turns that intent into durable effects
- how accounting entries and registers preserve business truth
- how audit history and reporting are connected to the same model
- how multiple vertical solutions reuse the same platform core
I also recorded a short architecture walkthrough video.
The short version
The core idea behind NGB is simple:
Business documents are intent. Posting creates durable effects. Reports read from durable business truth.
That separation is the foundation of the architecture.
A draft document means:
This is what the user wants to do.
A posted document means:
This business event is now part of durable system truth.
That distinction matters because serious business applications cannot rely on mutable CRUD state alone.
They need traceability.
They need auditability.
They need reporting.
They need a way to explain not only what the current value is, but also how the system got there.
The flow: from document to business truth
A typical NGB flow looks like this:
- A user creates or updates a document draft.
- The runtime validates the payload against metadata and business rules.
- The user posts the document.
- Posting creates durable effects.
- Those effects are persisted in PostgreSQL.
- Reports, document flows, audit history, and UI screens read from durable state.
That is the high-level path.
But each step exists for a reason.
Step 1: Document draft
In NGB, documents are first-class platform concepts.
A document is not just a row in a table.
It represents a business action with meaning.
For example, depending on the vertical, a document can represent:
- a lease
- a rent charge
- a payment
- a credit memo
- a sales invoice
- a purchase document
- a timesheet
- a work order
- a project invoice
At the draft stage, the document represents business intent.
It may be incomplete.
It may need validation.
It may still be edited.
It has not yet produced durable accounting or operational consequences.
This gives the system a clear boundary between:
- preparing a business action
- committing that action as system truth
That boundary is one of the most important parts of the architecture.
Step 2: Metadata and validation
NGB is metadata-driven.
That means the platform does not treat every form, grid, and payload as a one-off implementation.
Document and catalog definitions describe the structure of business objects.
The runtime can use those definitions to understand:
- available fields
- required fields
- payload shape
- document parts
- validation rules
- UI metadata
- reporting metadata
- allowed actions
This does not remove the need for business logic.
It creates a consistent foundation around it.
Instead of every vertical rebuilding the same infrastructure from scratch, vertical modules can focus on the business-specific rules that actually matter.
Step 3: Posting
Posting is the moment where a document becomes durable business truth.
This is not just a status update.
Posting is where NGB records the consequences of the business event.
A posted document may create:
- accounting entries
- operational register movements
- reference register updates
- document relationships
- audit log records
- reporting state
That means posting is a boundary.
Before posting, the document is intent.
After posting, the document has effects.
This is what makes the model different from a typical CRUD application where data is often edited in place and business consequences are scattered across services, triggers, reports, and custom tables.
Step 4: Accounting effects
NGB is accounting-first.
That does not mean every document is an accounting document.
It means the platform is designed with accounting semantics in mind from the beginning.
For money-moving or accounting-relevant events, posting can produce accounting entries.
Those entries are durable effects of the posted document.
The goal is not to hide accounting behind UI screens.
The goal is to make accounting consequences explicit, traceable, and reportable.
A report should be able to answer questions like:
- Which document created this accounting entry?
- Which period does it belong to?
- Which accounts were affected?
- Which dimensions were used?
- How does this line connect back to the business workflow?
That is why accounting is part of the architecture, not an afterthought.
Step 5: Append-only effects and reversals
For accounting-centric systems, silently rewriting history is dangerous.
NGB follows an append-only philosophy for durable effects.
The idea is:
Posted business effects should be preserved. Corrections should be explicit.
When something needs to be corrected, the system should not simply mutate historical truth in place.
Instead, it should use reversal or storno-style semantics where appropriate.
This makes the system easier to audit.
It also makes reports more trustworthy, because they are based on recorded effects rather than a constantly rewritten version of the past.
This approach is especially important for systems that need financial reporting, period close, audit history, and operational traceability.
Step 6: Operational registers
Not every business effect is a double-entry accounting entry.
Business systems also need operational state.
Examples include:
- open receivables
- settlement balances
- inventory quantities
- occupancy state
- work order progress
- project hours
- budget usage
- pending applications
- document relationships
NGB models this through operational registers.
Operational registers capture business state derived from posted documents.
They are not a replacement for accounting.
They are a complementary layer for operational truth.
Accounting can explain the financial effect.
Operational registers can explain the business state that the application needs to run workflows and reports.
Step 7: Reference registers
Some business facts are effective over time.
For example:
- prices
- rates
- policies
- account mappings
- configuration values
- reference facts
A value that is true today may not have been true last month.
A report or posting rule may need to know what value was effective at a specific point in time.
Reference registers help model this kind of time-aware reference data.
This matters because serious business systems often need historical correctness, not just current values.
Step 8: Audit history
Audit history is not optional in business software.
Users need to understand what changed.
Administrators need to understand who did what.
Developers need to debug business behavior.
Auditors need to trace facts back to their source.
NGB treats audit history as part of the platform foundation.
The goal is to make important business actions explainable:
- document creation
- posting
- reversal
- catalog changes
- period close
- workflow actions
- state changes
Auditability should not be something added later when the system becomes important.
It should be designed into the system from the beginning.
Step 9: Reporting
In many applications, reporting starts as a few SQL queries.
Then it becomes a collection of special cases.
Then it becomes difficult to maintain.
NGB treats reporting as a first-class platform subsystem.
The goal is to support both:
- canonical reports for important accounting and business scenarios
- composable reports for metadata-driven analysis
Reports should not be disconnected from the rest of the platform.
They should understand documents, catalogs, dimensions, filters, grouping, sorting, accounting effects, registers, and drilldowns.
A report should not just show numbers.
It should help users navigate back to the business facts behind those numbers.
That is why reporting belongs in the architecture.
Why this is different from typical CRUD
A typical CRUD system often starts with tables and screens:
Create table. Build form. Add list page. Add report later.
That can work for simple applications.
But serious business software needs more structure.
NGB starts from a different model:
Define business documents. Validate intent. Post durable effects. Preserve history. Report from business truth.
That difference changes the shape of the system.
The architecture is not centered only around tables.
It is centered around business events and their durable consequences.
One core, multiple verticals
NGB is not built around a single demo application.
The same platform concepts are reused across multiple vertical solutions.
Current demonstration verticals include:
Each vertical has its own domain model.
Each vertical has its own catalogs, documents, workflows, posting rules, and reports.
But they reuse the same core ideas:
- documents
- catalogs
- posting
- accounting effects
- operational registers
- reference registers
- audit history
- reporting
- metadata-driven UI
That is the point of the platform.
The goal is not to hardcode one industry solution.
The goal is to provide a reusable foundation for building accounting-centric vertical business applications.
Why .NET and PostgreSQL
NGB is built with a pragmatic stack:
- .NET
- PostgreSQL
- Vue
- Docker
- Kubernetes-oriented deployment practices
The important architectural choice is that PostgreSQL is treated as the system of record.
For this kind of software, the database is not just a persistence detail.
It is where durable business truth lives.
The .NET runtime orchestrates commands, validation, posting, reporting, and vertical behavior.
PostgreSQL provides transactions, constraints, data integrity, and durable storage.
Vue provides the web client layer.
The stack is intentionally practical.
For business systems, boring and reliable technology is often the right choice.
What the video covers
The architecture walkthrough focuses on the model behind NGB.
It covers:
- why CRUD alone is not enough for serious business software
- how documents represent business intent
- how posting creates durable effects
- how accounting entries and registers preserve business truth
- why append-only effects and reversals matter
- how operational and reference registers fit into the model
- how audit history and reporting connect to posted business events
- how Property Management, Trade, and Agency Billing reuse the same platform core
The video is not a UI demo.
It is an architecture walkthrough.
The goal is to explain the core model behind the platform.
What NGB is - and what it is not
NGB is an open-source platform foundation for accounting-centric business applications.
It is not just another generic web framework.
It is also not positioned as a finished replacement for every established ERP product.
Instead, I think of it as a reusable architecture and runtime foundation for teams that need to build serious business applications with:
- documents
- posting
- accounting effects
- operational state
- audit history
- reporting
- vertical extensibility
That is the space NGB is exploring.
Links
GitHub: https://github.com/ngbplatform/NGB
Docs: https://docs.ngbplatform.com
Website: https://ngbplatform.com
Architecture Brief: https://docs.ngbplatform.com/architecture/architecture-brief
Ecosystem Brief: https://docs.ngbplatform.com/ecosystem/erp-accounting-software-teams
Previous article: https://dev.to/ngbplatform/i-built-an-open-source-platform-foundation-for-accounting-centric-business-apps-b7g
Feedback welcome
I would especially appreciate feedback from people who have worked on:
- ERP systems
- accounting software
- vertical SaaS
- internal business platforms
- .NET architecture
- PostgreSQL-backed business systems
- reporting engines
- audit-heavy applications
The area I am most interested in discussing is the architecture itself:
How should serious business applications model documents, posting, accounting effects, operational state, audit history, and reporting without rebuilding the same foundation every time?
That is the problem NGB is trying to solve.
Top comments (0)