DEV Community: HideyukiMORI

Click a link, get a throwaway tenant: a zero-signup demo for a self-hosted app

HideyukiMORI — Wed, 08 Jul 2026 16:56:30 +0000

I maintain NeNe Invoice, a self-hosted invoicing OSS (PHP + SPA). Recently I needed to show it to people who are not engineers — and nothing kills a demo faster than "first, create an account."

What I wanted:

A URL you click. No signup, no login screen, no instructions.
Realistic data already inside — invoices, payments, overdue items.
No way for one visitor to see another visitor's mess.

Here is the demo, live (heads-up: the UI is Japanese — the product targets Japanese small businesses):

https://invoice.ayane.co.jp/demo/kensetsu (construction company)
https://invoice.ayane.co.jp/demo/bldmainte (building maintenance, recurring invoices)
https://invoice.ayane.co.jp/demo/seisaku (creative agency, withholding tax)

Every click provisions a brand-new disposable tenant and drops you on its dashboard. Three hours later, a cron job deletes it. This post is about how that works.

Why not the usual demo setups

A shared demo account is the easy option, and it's bad. Every visitor sees the previous visitor's test data. You end up writing a reset cron, and then someone gets reset mid-click.

A read-only mode protects the data by removing the product. "Create an invoice, register a payment, watch it reconcile" is the whole pitch — a demo where the write buttons are disabled demos nothing.

Disposable tenants solve both, if you already have multi-tenancy. That's the real precondition. My app already isolated everything by organization (each row carries an organization_id, every use case is org-scoped), so a demo mode became a thin layer of glue: about 900 lines including the seeder and the cleanup script, with zero changes to the auth core.

The flow

GET /demo/{template}
  → create org with a random slug        (normal CreateOrganization use case)
  → seed industry data into it           (DemoDataSeeder)
  → issue session cookies, path-scoped   (normal RefreshTokenIssuer)
  → 302 to /{slug}/dashboard

Nothing in that list is demo-specific infrastructure. Creating an org, creating its admin, issuing a refresh token — those are the same production use cases a real signup would call. The demo handler just calls them in a row and returns a redirect.

The pieces worth stealing

1. Gate it behind an env var, and 404

if ($this->env('DEMO_MODE', '0') !== '1') {
    return $this->problemDetails->create($request, 'not-found',
        'Not Found', 404, 'Demo mode is not enabled on this instance.');
}

/demo/* is a public, unauthenticated route, so on any instance that isn't the demo instance it shouldn't just be forbidden — it should not exist. A 404 (not a 403) means production installs don't even advertise that a demo feature is in the codebase.

2. Random slug, and the prefix is the contract

$slug = 'demo-' . bin2hex(random_bytes(4));   // demo-3f9a1c02

The demo- prefix does double duty: it namespaces the tenant and marks it as garbage-collectable. The cleanup script selects targets by this prefix alone, so it is structurally incapable of touching a real organization.

The admin password is random and never shown to anyone. There is deliberately no way to log into a demo org through the front door.

3. Seed data that never goes stale

Demo credibility lives and dies on seed data, and seed data has a classic failure mode: hardcoded dates. Six months after you write "invoice dated 2026-01-15", your demo shows an ancient dashboard.

All seeded dates are relative to today: a few invoices issued this month, one overdue, a couple paid last week. Whenever you click the link, the dashboard looks like a business that is alive right now.

The seeder also plants one deliberately messy case per template — a bank transfer whose payer name doesn't quite match the client name, waiting to be reconciled. Anyone who has done accounts receivable recognizes that pain instantly. One realistic wart sells the product better than ten clean records.

4. Session handoff without touching the auth core

The tricky part: after creating the org, the visitor must land inside it, authenticated, without seeing a login screen.

The handler issues the exact same refresh + CSRF cookies a real login would — but path-scoped to the new tenant's slug:

HTTP/2 302
set-cookie: ni_refresh=...; Path=/demo-5b067975/auth; Secure; HttpOnly; SameSite=Strict
set-cookie: ni_csrf=...;    Path=/demo-5b067975/;     Secure; SameSite=Strict
location: /demo-5b067975/dashboard

(That's a real response from the live demo.) The SPA loads, does its normal silent-refresh against /{slug}/auth/refresh, gets an access token, and renders. Token rotation, cookie contents, auth middleware: all untouched.

One trade-off accepted: the session is one-shot. Reload and you're back at the login screen. Fixing it would mean modifying the auth core for the demo's sake, so instead the demo leans into it — hitting the URL again gives you a fresh tenant, which is the "reset demo" button. With disposable tenants, reset isn't a feature you build; it comes free.

5. Cleanup that is allowed to be crude

A cron job runs hourly:

delete demo- orgs older than DEMO_TTL_HOURS (default 3)
also delete the oldest ones beyond DEMO_MAX_ORGS (default 200)

The second rule matters. TTL alone is fragile — if the cron stalls or someone scripts a thousand clicks, you want a hard cap on how much garbage can exist. With the cap, a bot hammering the demo link just churns its own tenants.

Child rows (invoices, line items, payments…) are bulk-deleted by organization_id, exceptions swallowed. Normally that's sloppy; here it's fine, and that's the point — when data is disposable by construction, the cleanup code gets to be simple.

Guardrails, summarized

Concern	Answer
Runs on production installs?	No — `DEMO_MODE=1` gate, 404 otherwise
Touching real tenants?	Impossible by construction (`demo-` prefix)
Login route into demo orgs?	None — random password, never disclosed
Data lifetime	3h TTL, hourly sweep
Abuse / DoS	Hard cap on org count, oldest evicted
"Reset the demo"	Not built — click the link again

The takeaway

The demo feature took a day. The reason it took a day is that years of boring discipline — tenant isolation on every row, org creation as a proper use case, token issuance behind an interface — had already paid for it. The glue layer got to be thin because the boundaries underneath were real.

If your app is multi-tenant, "click a link, get a throwaway tenant" is probably cheaper to build than the reset cron you were about to write for a shared demo account.

Code: src/Demo/ and tools/sweep-demo.php in NeNe Invoice (MIT).

Building a typed CMS for business data with PHP, OpenAPI, and MCP

HideyukiMORI — Thu, 02 Jul 2026 15:34:57 +0000

In my previous article, I introduced the NeNe series: a family of small, self-hosted business tools for teams operating in Japan.

https://dev.to/hideyukimori/i-am-building-self-hosted-business-tools-for-small-teams-in-japan-4i26

This article is a deeper look at one of those tools:

NeNe Records.

Repository:

https://github.com/hideyukiMORI/nene-records

NeNe Records is an API-first typed CMS and flexible entity platform built on NENE2, my small PHP framework for AI-readable business APIs.

It is not trying to be a WordPress clone.

It is not trying to run WordPress plugins or themes.

The goal is different:

manage business data and public content through typed schemas, documented APIs, and clear AI tool boundaries.

Why not just use WordPress?

WordPress is useful.

It has proven that a generic content model can support blogs, pages, shops, media, and many small business workflows.

But when I think about business data, a few problems keep coming back:

untyped metadata
plugin-specific data shapes
hooks and filters that can change behavior from many places
API contracts that depend heavily on plugins
AI integrations that may not know where the real application boundary is

The postmeta model is flexible, but it often becomes stringly typed storage.

That is fine for many websites.

But for business data, I usually want the API to know more:

this field is text
this field is an enum
this field is an image
this field is a relation
this field is required
this record belongs to this organization
this operation requires this role

That is the space where NeNe Records lives.

Typed records instead of metadata chaos

The core model is simple:

Entity Type
  -> Field Definition
  -> Record

An Entity Type defines what kind of data exists.

Examples:

posts
pages
products
events
internal documents

A Field Definition describes the shape of a field:

text
markdown
html
blocks
int
enum
bool
datetime
image
file
relation

A Record is the actual data.

The important part is that the schema is not only a frontend concern.

The API validates writes against the registered field definitions.

The admin UI can provide a flexible editing experience, but the API remains the boundary that enforces the data shape.

That is the main difference I care about:

flexible editing, typed persistence.

Current status

NeNe Records is already more than a schema experiment.

It has a React admin UI, typed entity definitions, record management, media handling, public pages, OpenAPI documentation, and an OpenAPI-derived MCP tool catalog.

It also supports multi-tenant organization scope, with ongoing work around WordPress migration and production deployment.

It is still a work in progress, but the core shape is already running.

The architecture

NeNe Records follows the same general shape as the rest of the NeNe series:

React Admin UI
Public pages
AI / MCP clients
        |
        v
Documented HTTP API
        |
        v
Use cases
        |
        v
Repositories
        |
        v
Database

The backend is PHP 8.4 on NENE2.

The admin UI is React and TypeScript.

The API contract is OpenAPI 3.1.

MCP tools are derived from the documented API surface.

The important rule is:

MCP tools should call the application API, not the database.

That is the same rule I wrote about in my previous article:

https://dev.to/hideyukimori/mcp-should-not-mean-letting-ai-touch-your-database-57p1

For a CMS-like product, this matters a lot.

Content and business data are not just rows.

They have:

validation rules
permissions
organization scope
publication state
redirects
SEO metadata
media references
audit and migration concerns

Those rules belong in the application boundary.

API-first admin

The admin screen is not the source of truth.

It is a client.

It edits entity types, fields, records, media, users, and settings through the same API shape that other clients can understand.

This makes the system easier to reason about.

If a future tool needs to create a record, it should not need a hidden internal shortcut.

It should call the same API that the admin UI calls.

That is also why OpenAPI matters.

The API contract is not only documentation for humans.

It is also a map for:

generated clients
contract tests
MCP tool catalogs
future automation

Public pages without a separate Node SSR server

NeNe Records is not only a headless CMS.

It also supports public pages.

The direction is a single-origin PHP application that can return crawlable HTML for public content, with a SPA shell on top.

That includes work around:

real permalinks
canonical URLs
OGP
Twitter cards
JSON-LD
breadcrumbs
sitemap.xml
robots.txt
redirect maps

I do not want every small business deployment to require a separate Node SSR service just to make public pages crawlable.

For this project, the PHP application should be able to serve useful public HTML directly.

WordPress migration, not WordPress compatibility

NeNe Records is not WordPress-compatible.

That is intentional.

But migration still matters.

Many real teams already have content in WordPress.

So NeNe Records has been growing a WXR import path:

posts and pages
tags
media attachments
body image URL replacement
301 redirect maps
SEO metadata from common plugins
import plan preview

The goal is not:

run WordPress themes and plugins.

The goal is:

move content, URLs, media, and SEO intent into a typed API-first platform.

That distinction is important.

Compatibility with the WordPress runtime would pull the product back toward the same plugin/theme coupling I am trying to avoid.

Migration is the useful part.

Runtime compatibility is not the goal.

Real-data testing with Aozora Bunko

One thing I have been doing recently is testing NeNe Records with real public-domain text data.

For that, I prepared an importer using Aozora Bunko text.

In a test tenant, I imported works by Natsume Soseki as chapter-based records.

The goal is not just to prove that records can be inserted.

The goal is to see whether the system still feels coherent when the data is not a tiny demo.

Things I want to observe:

list performance with many records
permalink tree behavior
chapter navigation
public page rendering
sitemap behavior
search and directory browsing
admin UI usability with larger content sets

The public test tenant is here:

https://aozora.nene-records.com/

In a browser, it is intended to show the public shell.

If you call it with curl and the default Accept: */*, you may see an API-style JSON response instead. Normal browser access should resolve as HTML.

This kind of real-data testing is valuable because CMS demos can be misleading.

A CMS with five records can look finished.

A CMS with hundreds or thousands of records starts to reveal where the model, navigation, and public presentation are weak.

Why this is business software, not only a CMS experiment

I call NeNe Records a typed CMS, but the broader idea is a flexible entity platform.

The same primitives can describe more than blog posts:

product catalogs
internal knowledge records
simple CRM data
public directories
structured landing pages
operational records

The difference from an application framework is that Records keeps the schema editable from the product surface.

The difference from a traditional CMS is that the API and field definitions are not treated as incidental plugin behavior.

They are the center.

What is still unfinished

I do not want to overstate the maturity.

NeNe Records is still being refined.

Important areas are still evolving:

settings UI
finer-grained permissions
two-factor authentication
production deployment paths
hosted / managed options
more public-site polish
large-data soak testing

The project is open source and usable for experimentation, but I do not want to present it as a finished CMS replacement.

The honest position is:

the shape is working, and the product is being hardened through real implementation.

What I learned while building it

The biggest lesson is that "simple CMS" is not actually simple.

Once you care about typed data, SEO, public pages, migration, multi-tenancy, media, admin UX, and AI boundaries, the system becomes a real product very quickly.

That is why the architecture needs to stay boring.

The boring parts are the parts I want to trust:

HTTP APIs
OpenAPI contracts
use cases
repositories
typed field definitions
explicit permissions
MCP behind the API boundary

The product can become flexible only if the boundaries stay strict.

I am building self-hosted business tools for small teams in Japan

HideyukiMORI — Tue, 30 Jun 2026 13:51:32 +0000

I have been building a small family of open source business tools called the NeNe series.

The idea is simple:

small teams should be able to run useful business software on their own infrastructure, with clear APIs and readable boundaries.

Most of the tools are still being refined, but the direction is already visible:

self-hosted
API-first
bilingual where Japan operations need it
OpenAPI documented
MCP-ready for AI agents
small enough for one developer or a small team to understand

The foundation is NENE2, my PHP 8.4 API-first micro-framework.

Repository:

https://github.com/hideyukiMORI/NENE2

GitHub profile:

https://github.com/hideyukiMORI

Why Japan-specific business tools?

Many teams operating in Japan have a mixed workflow.

The technical team may be comfortable with English.

The business workflow is still deeply local:

qualified invoices
received-document retention
payment reconciliation
Japanese bank CSV formats
bilingual admin screens
small company operations

Generic tools can work.

But sometimes the local workflow leaks through the cracks.

That is why the NeNe series is not just “another CRUD app collection”.

It is an attempt to build small, self-hosted tools that understand specific business boundaries.

The products

The series includes several focused tools.

NeNe Invoice

Self-hosted quote and invoice management for Japan small businesses.

It focuses on qualified invoices, quotes, invoices, payments, PDF output, and admin UI workflows.

Repository:

https://github.com/hideyukiMORI/nene-invoice

Japanese hands-on article:

https://qiita.com/xioncc/items/7439c9832a6795b4d48e

NeNe Vault

Received-document archive for PDFs and business documents.

It focuses on storing received invoices, receipts, and contracts with search, audit history, and retention-oriented workflows.

Repository:

https://github.com/hideyukiMORI/nene-vault

Japanese hands-on article:

https://qiita.com/xioncc/items/2f3726347e4504363534

NeNe Deal

Lightweight B2B deal pipeline management.

It handles opportunities, stages, simple forecasts, and handoff to NeNe Invoice as draft client / quote data.

Repository:

https://github.com/hideyukiMORI/nene-deal

Japanese hands-on article:

https://qiita.com/xioncc/items/5f7f0e3687d77f07e00e

NeNe Contact

Embeddable contact forms and an operator inbox.

It lets operators build forms, embed them with a script tag, receive submissions, manage statuses, and route notifications.

Repository:

https://github.com/hideyukiMORI/nene-contact

Japanese hands-on article:

https://qiita.com/xioncc/items/580750a119ffaa1641af

NeNe Records

API-first typed CMS / flexible entity platform.

It lets users define entity types, typed fields, records, public pages, and OpenAPI/MCP-facing operations.

Repository:

https://github.com/hideyukiMORI/nene-records

What ties them together?

The products are different, but they share the same direction.

1. API-first boundaries

The API is the contract.

Admin screens, public pages, integrations, and AI tools should go through documented HTTP APIs.

That makes behavior easier to test, review, and expose safely.

2. OpenAPI as a shared language

Each product aims to document its public API with OpenAPI.

That matters for human developers.

It also matters for AI agents.

If the API is explicit, a tool can map to the operation without guessing database structure.

3. MCP should call the app

I wrote about this in my previous article:

https://dev.to/hideyukimori/mcp-should-not-mean-letting-ai-touch-your-database-57p1

My rule of thumb is:

MCP tools should wrap application capabilities, not bypass the application.

That means:

AI Agent
  -> MCP Tool
  -> documented HTTP API
  -> handler
  -> use case
  -> repository / transaction boundary

Not:

AI Agent
  -> MCP Tool
  -> direct SQL query
  -> production database

4. Boring architecture on purpose

The stack is intentionally not magical.

Most products follow a shape like:

Handler
  -> Use Case
  -> Repository

The frontend is a client.

The database stays behind repositories.

The MCP layer stays behind HTTP APIs.

This is boring.

That is a feature.

Why PHP?

Because PHP still matters for small business software.

It is widely deployable.

It is easy to host.

It is familiar to many developers who work on business systems.

Modern PHP can be strict, typed, tested, and API-first.

NENE2 is my attempt to keep PHP small and explicit instead of recreating a large full-stack framework.

What is NENE2?

NENE2 is the small framework underneath many of these tools.

It provides:

PSR-style HTTP runtime
explicit routing
Problem Details error responses
OpenAPI contracts
database boundaries
auth middleware
optional frontend starter patterns
local MCP server support

It is not trying to replace Laravel.

It is a small foundation for building business APIs that humans and AI agents can both understand.

First DEV article:

https://dev.to/hideyukimori/i-built-a-tiny-php-framework-for-ai-readable-business-apis-48eo

This is still a work in progress

I do not want to overstate the maturity of the portfolio.

Some tools are close to formal release.

Some are still being refined.

Some deployment paths are Docker-first today, with shared-hosting or managed paths still evolving.

The goal of the articles I am publishing now is not to claim that every product is finished.

The goal is to make the architecture, direction, and working software visible.

What I am looking for

I am especially interested in feedback from people who care about:

self-hosted business software
API-first PHP
OpenAPI contracts
MCP and AI agent boundaries
small tools for real operational workflows
software for teams operating in Japan

If you are building similar tools, or thinking about how AI agents should interact with business APIs, I would be happy to hear your perspective.

MCP should not mean letting AI touch your database

HideyukiMORI — Thu, 25 Jun 2026 13:18:14 +0000

After publishing my first article about NENE2, a small PHP framework for AI-readable business APIs, one comment stood out:

consistent JSON envelopes matter more than ever when agents are parsing responses.

I agree.

But predictable JSON is only one part of the story.

The bigger question is:

What should an AI agent be allowed to touch?

My answer is simple:

An MCP tool should call your application boundary, not your production database.

MCP is not a license to bypass the app

MCP is useful because it gives AI tools a structured way to call capabilities.

But if we use it carelessly, it can become a very polished shortcut around the application:

AI Agent
  -> MCP Tool
  -> direct SQL query
  -> production database

That may feel convenient during a demo.

It is also exactly the kind of thing I do not want in business software.

The database does not know the full application rules:

validation
authorization
tenant isolation
domain invariants
audit logging
rate limits
Problem Details error behavior
request IDs
business workflow state

Your application knows those things.

So the agent should go through the application.

The safer shape

The direction I use in NENE2 is:

AI Agent
  -> MCP Tool
  -> documented HTTP API
  -> handler
  -> use case
  -> repository / transaction boundary

This is less magical.

That is the point.

If an AI agent asks for the status of a record, the tool should call the same read API that a normal client would call.

If an AI agent creates or updates something, the tool should call the same write API that already validates the request, checks credentials, logs the request, and returns a predictable error shape.

MCP should expose application capabilities.

It should not invent a second, hidden application.

OpenAPI as the tool contract

In NENE2, OpenAPI is the public API contract.

That makes it a natural starting point for MCP tool definitions.

If the HTTP API says:

GET /examples/notes/{id}

then an MCP tool can map to that operation:

getExampleNoteById

The tool does not need to know where the note is stored.
It does not need SQL.
It does not need to load a .env file.

It needs:

a tool name
a JSON input schema
an HTTP method and path
the API base URL
credentials when required
a way to preserve errors and request metadata

The API remains the contract.

Read tools first

I think most MCP integrations should start with read tools.

Read tools are easier to reason about:

health checks
list records
get one record
inspect history
export a manifest
summarize a dashboard

They still need authorization when the data is private, but they do not mutate state.

That makes them a good first milestone for teams learning how agents interact with their product.

In NENE2, MCP tools have safety levels such as:

read
write
admin
destructive

The first tools should usually be read.

Write tools need more design.

Admin and destructive tools need even more.

Write tools need authentication and audit

Write tools are not forbidden.

But they should not be treated as a weekend shortcut.

A write tool needs the same kind of design you would expect from any sensitive API:

authentication
authorization
request validation
audit fields
request ID propagation
useful error responses
tests for failure and permission boundaries
confirmation behavior for destructive actions

In local NENE2 development, write tools can call documented write endpoints.

When NENE2_LOCAL_JWT_SECRET is configured, write tools require a valid Bearer JWT.

For production tools, the bar should be higher:

owner
allowed environments
required scopes
rate limits
logging policy
rollback or remediation behavior

Production MCP tools are product features.

They are not debugging shortcuts.

Problem Details matter

When an MCP tool calls an HTTP API, it should preserve the API's error behavior.

For NENE2, that means RFC 9457 Problem Details.

If a request is invalid, the agent should see a structured error.

If authentication fails, the agent should see a structured 401.

If a domain object is not found, the agent should see a structured 404.

The tool should not collapse everything into:

Something went wrong.

Agents need predictable failure shapes too.

Good error contracts are part of AI-readability.

Credentials should stay out of the repository

This sounds obvious, but it matters.

MCP configuration often lives close to developer tooling.

That makes it tempting to commit values that should never be committed:

API keys
bearer tokens
local secrets
private paths
database URLs

NENE2's guidance is:

document environment variable names
do not commit secret values
do not return credentials in tool metadata
do not let MCP tools read raw .env secrets
do not print tokens in logs

A tool can say it requires a scope.

It should not expose the credential.

Where nene-mcp fits

I also maintain nene-mcp, a small PHP stdio MCP bridge.

It can expose HTTP APIs as MCP tools using a committed tools.json catalog.

The shape is intentionally simple:

MCP client
  -> stdio JSON-RPC
  -> nene-mcp
  -> HTTP API

It is not a customer-facing API gateway.

It is a sidecar for local development, staging, and small team workflows.

It works best when the application already has documented HTTP endpoints and a clear tool catalog.

That is the same idea again:

MCP should call the app, not bypass it.

A concrete rule of thumb

When designing an MCP tool, I like to ask:

Could a normal HTTP client safely do this through the documented API?

If yes, the MCP tool is probably a good wrapper.

If no, I ask another question:

Why does this capability exist only for the agent?

Sometimes there is a good answer.

Often there is not.

If the capability is real business behavior, it probably deserves an application API, tests, documentation, and review.

What this means for "AI-readable" APIs

An AI-readable API is not just an API with JSON.

It is an API where:

the routes are discoverable
the schemas are predictable
the errors are structured
the boundaries are explicit
credentials are handled deliberately
tools map to documented operations
business rules are not hidden in a side channel

This is the design direction behind NENE2.

It is also why I prefer boring architecture:

Handler
  -> Use Case
  -> Repository

The agent can understand it.

The developer can review it.

The tests can cover it.

The database stays behind the application boundary.

I built a tiny PHP framework for AI-readable business APIs

HideyukiMORI — Mon, 22 Jun 2026 13:25:37 +0000

I have been building a small PHP framework called NENE2.

It is not a Laravel replacement.
It is not a full-stack framework.
It is not trying to hide everything behind magic.

NENE2 is a tiny, API-first PHP foundation for building AI-readable business APIs: small services with explicit HTTP boundaries, OpenAPI contracts, Problem Details errors, and optional MCP tool catalogs for AI agents.

Repository: hideyukiMORI/NENE2

Why build another PHP framework?

Most business software does not start as a beautiful greenfield platform.

It starts as a request like:

"Can we expose this workflow as an API?"
"Can an internal tool call this safely?"
"Can an AI agent look up the status without touching the database?"
"Can we keep this small enough that a team can actually understand it?"

Large frameworks are great when you need their ecosystem.

But for small business APIs, I often want something quieter:

explicit routes
small handlers
use cases that do not know about HTTP
repository interfaces
OpenAPI as the public contract
predictable error responses
tests that prove the behavior
a clean boundary for AI / MCP tools

That is the design space where NENE2 lives.

The core idea: API first, AI readable

NENE2 assumes that the API is the primary surface.

Server-rendered HTML can exist, and a React frontend starter can exist, but the backend should not become frontend build glue. The stable contract is the HTTP API.

The framework is organized around:

PSR-7 / PSR-15 / PSR-17 HTTP runtime direction
explicit routing and middleware
OpenAPI 3.1 contract documentation
RFC 9457 Problem Details for errors
typed configuration objects
PSR-11 dependency injection
PDO database adapters and transaction boundaries
optional React + TypeScript frontend starter
local MCP server support behind the same API boundary

The goal is not to make the code clever.

The goal is to make the code easy to inspect by a human developer, a reviewer, or an AI coding agent.

A boring architecture on purpose

The reference domain example follows a simple flow:

HTTP Handler
  -> Use Case
  -> Repository Interface
  -> PDO Adapter

For example, the Note CRUD reference implementation includes:

route + handler classes
use case classes
readonly input/output DTOs
repository interface
PDO repository
exception-to-Problem-Details mapping
OpenAPI paths and schemas
unit, HTTP, and PDO integration tests

This is intentionally boring.

I want application behavior to be visible in the file tree instead of being implied by framework convention.

OpenAPI is the handoff document

For NENE2, OpenAPI is not an afterthought.

The repository ships an OpenAPI 3.1 document, Swagger UI, and runtime contract tests for example endpoints.

Locally, after starting the app:

docker compose up -d app

Useful URLs include:

http://localhost:8200/health
http://localhost:8200/examples/ping
http://localhost:8200/openapi.php
http://localhost:8200/docs/

This matters because the OpenAPI file is also the bridge to other tools:

generated clients
contract tests
documentation
MCP tool catalogs
AI-assisted development workflows

The API contract is the shared language.

MCP should not mean "let AI touch the database"

One of the ideas behind NENE2 is that AI agents should operate through documented API boundaries.

I do not want an agent to directly query or mutate production tables.

Instead:

AI Agent
  -> MCP Tool
  -> documented HTTP API
  -> application use case
  -> repository / transaction boundary

NENE2 includes local MCP server support and guidance for mapping tools to OpenAPI-backed operations.

Read tools can inspect state.
Write tools require explicit authentication.
The application still owns validation, authorization, logging, and error handling.

That boundary is the important part.

Field-tested through real apps

NENE2 is not only a framework repository.

I have been using it as the foundation for a family of self-hosted business OSS projects, including:

NeNe Invoice — quote and invoice management for Japan qualified invoices
NeNe Vault — received-document archive for electronic record retention
NeNe Records — typed headless CMS / flexible entity platform
NeNe Deal — lightweight B2B deal pipeline
NeNe Contact — embeddable contact forms
nene-mcp — stdio MCP bridge for OpenAPI-backed HTTP APIs
nene2-python — Python reference implementation of the same philosophy
nene2-js / nene2-node — TypeScript ecosystem pieces

Some of these products are Japan-specific.
That is fine.

The point is that the framework is tested against real business shapes:

authentication
multi-tenancy
OpenAPI
admin UIs
Docker local stacks
database migrations
exports
audit logs
MCP catalogs
AI-readable documentation

Framework design gets better when it is forced through real applications.

What NENE2 is not

NENE2 is deliberately small.

It is not:

a Laravel or Symfony replacement
a no-code platform
an ORM-first framework
a CMS
a frontend framework
an AI agent runtime

It is a small foundation for teams or solo developers who want explicit PHP APIs and documented handoff points.

Quick start

Clone the repository:

git clone https://github.com/hideyukiMORI/NENE2.git
cd NENE2
cp .env.example .env
docker compose build
docker compose run --rm app composer install
docker compose run --rm app composer check
docker compose up -d app

Or install it as a Composer dependency:

composer require hideyukimori/nene2

NENE2 targets PHP 8.4+ and uses Docker as the standard development runtime.

Why "AI-readable" matters

AI-assisted development is not only about generating code.

It is also about whether the system is readable enough for an agent to help safely:

Can it find the route?
Can it understand the request and response shape?
Can it see the use case?
Can it run the focused tests?
Can it avoid bypassing validation?
Can it call a documented tool instead of guessing a database query?

NENE2 tries to make those answers obvious.

Not by adding more magic.

By removing ambiguity.

DEV Community: HideyukiMORI

Click a link, get a throwaway tenant: a zero-signup demo for a self-hosted app

Why not the usual demo setups

The flow

The pieces worth stealing

1. Gate it behind an env var, and 404

2. Random slug, and the prefix is the contract

3. Seed data that never goes stale

4. Session handoff without touching the auth core

5. Cleanup that is allowed to be crude

Guardrails, summarized

The takeaway

Building a typed CMS for business data with PHP, OpenAPI, and MCP

Why not just use WordPress?

Typed records instead of metadata chaos

Current status

The architecture

API-first admin

Public pages without a separate Node SSR server

WordPress migration, not WordPress compatibility

Real-data testing with Aozora Bunko

Why this is business software, not only a CMS experiment

What is still unfinished

What I learned while building it

Links

I am building self-hosted business tools for small teams in Japan

Why Japan-specific business tools?

The products

NeNe Invoice

NeNe Vault

NeNe Deal

NeNe Contact

NeNe Records

What ties them together?

1. API-first boundaries

2. OpenAPI as a shared language

3. MCP should call the app

4. Boring architecture on purpose

Why PHP?

What is NENE2?

This is still a work in progress

What I am looking for

Links

MCP should not mean letting AI touch your database

MCP is not a license to bypass the app

The safer shape

OpenAPI as the tool contract

Read tools first

Write tools need authentication and audit

Problem Details matter

Credentials should stay out of the repository

Where nene-mcp fits

A concrete rule of thumb

What this means for "AI-readable" APIs

Links

I built a tiny PHP framework for AI-readable business APIs

Why build another PHP framework?

The core idea: API first, AI readable

A boring architecture on purpose

OpenAPI is the handoff document

MCP should not mean "let AI touch the database"

Field-tested through real apps

What NENE2 is not

Quick start

Why "AI-readable" matters

Links