> > > PhilosophyPragmaticArchitectureScopeDiscipline

Pragmatic Architecture and Scope Discipline

Thesis

SOTER treats architecture as a tool for protecting the domain core, not as a ceremony imposed uniformly on every repository. Hexagonal architecture is valuable where a stable domain core must be insulated from volatile infrastructure, external systems, or rendering adapters. It is wasteful when it is used to disguise scope creep, postpone product decisions, or wrap simple glue code in unnecessary abstractions.

The governing rule is pragmatic: introduce ports where the boundary is real, costly, and likely to change. Do not introduce a full hexagonal shell merely because a project has grown beyond its intended proof-of-concept size. A large scope problem is solved by cutting scope, not by adding layers.

Problem

The portfolio around SOTER includes product systems, auxiliary tooling, and infrastructure. Their architectural needs are not identical. A uniform rule such as "every repository must become hexagonal" confuses several different concerns:

reducing MVP scope;
organizing internal modules;
protecting a domain core behind ports;
extracting operationally independent services.

These concerns may reinforce one another, but they are not the same decision. Scope reduction belongs on the board. Module boundaries belong in package and service structure. Ports belong at unstable or expensive integration seams. Service extraction belongs only where operational independence justifies the extra cost.

Argument

Scope Is Not Coupling

Hexagonal architecture addresses coupling between domain logic and external mechanisms. It does not make a product smaller. It often increases code volume by adding ports, adapters, DTOs, registries, and mapper layers.

For an MVP, this distinction is decisive. The point of an MVP is to answer a validation question with the smallest maintainable surface. Every delivered feature becomes a support obligation. A solo-maintained product therefore needs fewer supported behaviors, not a larger abstraction framework around behaviors that may be removed after validation.

Ports Belong Where the Boundary Hurts

A port earns its place when one of the following conditions is true:

the external mechanism is likely to be replaced;
the boundary must be faked in tests;
the dependency has independent availability, latency, or release behavior;
the domain core would otherwise import concrete infrastructure;
the adapter expresses a separate operational responsibility.

Typical MVP ports are external APIs, LLM providers, payment providers, government systems, persistence backends, search engines, authentication providers, and projection/rendering backends. Ordinary CRUD code does not automatically deserve a port. Infrastructure scripts and deployment glue usually do not have a domain core to protect.

The Board Cuts Scope

Backlog structure is the primary instrument for reducing PoC and MVP drift. Work should be organized through a small set of common fields across related projects:

Status: Backlog, Todo, In Progress, Blocked, Done;
Type: Epic, User Story, Task;
Epic: parent theme;
Milestone: Pilot, MVP, v1.0, Parking;
Priority: P0, P1, P2;
Aspect: Dev, Product, UX, Ops, QA, Business, Analysis, when useful.

Milestone belongs on the deliverable leaf item, not on the epic. Epics often cross milestones. The milestone matrix is therefore a view over leaf items: epics form one axis, milestones form the other, and concrete user stories or tasks occupy the cells.

Discovery work must also be classified carefully. Resolved discovery should be closed. Discovery that blocks MVP scope is not Parking; it is a blocker or a reason to descope the dependent feature. Future exploration with no current dependency belongs in Parking. Build work such as design tokens, component libraries, accessibility, and responsive behavior is not discovery merely because it is not backend code.

Milestones Are Exit Criteria

Progress is measured by complete usable slices, not by percentage completion or lines of code. A project with many nearly-finished capabilities still has no deliverable milestone if a required capability such as login, role separation, or basic data entry is missing.

The current position of a product is the highest milestone whose exit criteria are satisfied in full. If MVP has twelve criteria and three remain open, the project is still before MVP, even if most code already exists.

This rule supports a narrow maintenance surface. A product should aim to satisfy the core user need with the smallest coherent feature set. Meeting most of a customer's requirements with a smaller number of supported features is better than shipping a broad surface that cannot be maintained.

Repository-Level Implications

SOTER

SOTER has a real domain core: Logos parsing, semantic analysis, ontology validation, VGM generation, and fact/model reconciliation. Hexagonal boundaries are appropriate where this core would otherwise depend on concrete projection, ledger, persistence, or UI mechanisms.

The most important rule is directional: the core depends on abstractions, not on concrete projectors or ledger implementations. Projectors are adapters that translate VGM or render plans into PlantUML, Mermaid, BPMN, SVG, D2, or other formats. The core should expose a projector port and let adapter-side code register concrete projectors.

The first SOTER MVP question is not whether every projection and ledger integration works. It is whether Logos can catch syntactic, stylistic, semantic, and basic ontological errors well enough to improve internal model validation. Diagram generation and fact confrontation are later validation slices unless one minimal projector is needed to make the product promise visible.

Akasha

Akasha is justified as a separate concern because ledger persistence and fact audit have a different lifecycle from Logos model validation. SOTER core writes facts through a write-side abstraction. Read-back belongs to a plugin, reader library, or external reader service, not to the pure model-validation core.

Akasha extraction should not turn the ledger API into the domain boundary. The boundary is the canonical fact contract. SOTER emits facts to a sink; file logs, local Akasha, remote Akasha, or later audit services are adapters.

SEOS

SEOS should not be forced into full hexagonal architecture before its product scope is stable. The first slice is operational: users can log in with relevant roles and perform project and cost CRUD. CEIDG, KSeF, audit history, kanban, import/export, and SOTER integration are outside the MVP unless explicitly pulled into the validation question.

Ports make sense at external integration seams such as KSeF, CEIDG, accounting systems, tenant provisioning, and optional audit export. A future SEOS to Akasha integration should be generic: SEOS may write to an external audit sink, of which Akasha is one implementation. SEOS must remain useful without Akasha.

SELECTjob

SELECTjob's MVP is crawler-centered: preconfigured employer domains are scanned, offers are refreshed, changes are detected, and a user can search results with a free-text query. User accounts, employer CRUD, ATS features, branding, subscriptions, analytics, and advanced dashboards belong outside that first slice unless they are required to validate crawler usefulness.

Ports are justified around crawler sources, payment providers, search backends, and outgoing webhooks. Elasticsearch is not required for the first validation if PostgreSQL full-text search can answer the search hypothesis with less maintenance cost.

app-runner and infra

app-runner already acts as a kernel with adapters for service types and should serve as a reference for pragmatic modularity. It does not need a ceremonial rewrite.

Infrastructure code is primarily deployment glue. It normally has no business domain core to protect with hexagonal architecture. Its quality comes from clarity, repeatability, and operational safety, not from ports and adapters.

Implications for SOTER

SOTER's architecture should remain model-driven and hexagonal at the domain boundary, but not indiscriminately layered. The strict core contains Logos, semantic validation, ontology rules, VGM, and reconciliation concepts. Adapters perform projection, persistence, UI, external audit, and integration work.

The architecture should therefore enforce three constraints:

the core does not import concrete adapters;
adapters translate core contracts without adding domain meaning;
MVP scope is cut by validation question, not by package rearrangement.

This discipline also constrains AI-assisted development. An agent working on SOTER should not expand architecture by analogy. It should identify the current validation question, preserve the core boundary, and place new code either in the pure core or in an adapter with an explicit reason.

Boundaries

This essay does not define the full Akasha fact schema, the Logos grammar, the VGM contract, or the projector registry. It also does not prescribe a single board implementation. It states the architectural and planning principles that govern those specifications.

Operational Consequences

Treat scope creep as a board problem before treating it as an architecture problem.
Add a port only at a boundary with real volatility, test cost, or availability risk.
Keep milestone assignment on leaf work items.
Use Blocked when WIP is limited and a task cannot proceed.
Keep SOTER core independent from concrete projector and ledger adapters.
Keep SEOS usable without Akasha, even if SEOS later becomes the reference integration.
Do not apply hexagonal architecture to infrastructure glue unless a genuine domain core emerges.

Open Questions

Which single projector, if any, belongs in the first SOTER validation slice?
Should the SOTER MVP include a basic ontological rule layer, or only syntax, style, and semantic checks?
Which SEOS board items are true MVP blockers rather than future discovery?