BaryoDev / BaryoDev/barakoCMS

A module cannot say it has a console screen, so every module needs hand-written code in another repo

Open
#635 1 comment 0 reactions 0 assignees View on GitHub
core enhancement module
Dominant language
C#
Stars
6
Forks
7
Avg merge
4h 42m
Merged PRs (30d)
307

Description

A module ships endpoints and documents and has no way to say it should appear in the console. `MODULES.md` walks an author through services, schema, endpoints, capabilities and seeding, and never mentions the console at all. `GET /api/modules` reports three fields, name, contract version and enabled, which cannot describe a screen.

So today every module needs hand-written code in `BaryoDev/barakoBrew`: `use-accounting.ts`, `use-feature-flags.ts`, `use-analytics.ts` are each bespoke. barakoBrew#3 records four modules with endpoints and no screen.

That does not scale with first-party modules and it does not work at all for third-party ones. An outside author cannot open a pull request into the console for their own package, and if they could, the console becomes a directory of other people's screens.

## What to add

A UI descriptor on the module contract, reported through `GET /api/modules`, describing what the console should draw:

- the documents the module owns, and the fields on each, using `FieldTypeRegistry` names so the console's existing renderer already understands them;
- which capability gates each screen and each action, so the console shows what the caller may actually use rather than hiding what the server will refuse;
- the actions a screen offers, and the endpoint each calls;
- where it belongs in the navigation.

`ContentTypeDefinition` and `FieldTypeRegistry` are the model to copy. They already drive the console's `dynamic-form.tsx` for content, which is why a module whose data is content types has an editor today and one with its own documents does not.

## Deliberately not a UI bundle

The alternative is module federation: the module ships JavaScript and the console loads it. Strapi and Umbraco both do that, and it buys unlimited UI.

It also runs third-party code inside an authenticated admin session, with the operator's token, every tenant they can reach and every field on screen. That is the opposite of the property this codebase is built on, that a dangerous thing is refused by construction rather than trusted. `RequestComposer` will not send a non-Public field even when an operator asks it to; loading a stranger's bundle into the console undoes that in one step.

A descriptor keeps it: the module describes, the console renders, and the worst a hostile descriptor achieves is an ugly form.

**The cost, stated plainly:** a descriptor expresses only what its language expresses. The accounting ledger and the media grid will not come out of it, and they stay hand-written. That is acceptable because they are first-party. It is not acceptable to have no answer at all for the third-party case, which is where we are.

## Decide before inviting authors

This is a contract change, so `ModuleContract.Version` and `DECISIONS.md` D18 both bear on it. D18 already promises module authors a replacement for `ConfigureMarten` before 5.0 removes it, and a deprecation window for every added member. A descriptor is the same class of promise: once authors build against it, its shape is fixed.

The ecosystem cannot start before 4.0 is tagged, because `BarakoCMS.Templates` and `BarakoCMS.Testing` are not published. That makes this the cheap moment, while the number of outside modules is zero.

## Done when

- A module can declare its screens, and `GET /api/modules` reports them.
- `MODULES.md` documents the descriptor next to the rest of the contract, so an author reads one file.
- The `barakocms-module` template scaffolds a descriptor, so the default is to have one.
- A test asserts a module declaring a capability the caller lacks does not have that screen described to them.

Counterpart: BaryoDev/barakoBrew renders it. Neither half is useful alone.

Contributor guide

Open the contributing guide

Research direction

Start with MODULES.md, the GET /api/modules entry point, ModuleContract.Version, and DECISIONS.md D18 to understand the existing contract and compatibility promises. Review ContentTypeDefinition and FieldTypeRegistry as the stated model, then inspect the barakocms-module template and existing module tests. Done means the descriptor is reported, documented, scaffolded, and covered by the capability-filtering test described in the issue.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
api, backend-api-design, documentation, testing
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.