BaryoDev / BaryoDev/barakoBrew

Overview: lead with what needs a decision, and find a source for what the design displays

Open
#9 3 comments 0 reactions 1 assignee Claimed by @arnelirobles View on GitHub
enhancement
Dominant language
TypeScript
Stars
1
Forks
2
Avg merge
4h 34m
Merged PRs (30d)
60

Description

Part of BaryoDev/barakoBrew#8. The most expensive screen in the handoff, and the one with the most that has no data source.

Spec: `docs/design/barakobrew-2026/README.md`, screen 2. Screenshot: `docs/design/barakobrew-2026/screenshots/02-admin-overview.png`. Current: `src/app/(admin)/page.tsx`.

The redesign is right about the intent. Today's Overview shows three stat cards and a list of recent entries, none of which asks anyone to decide anything. The new one leads with what needs a decision. The cost is that most of what it displays does not exist yet.

## The event stream needs a decision first, and it is not a UI decision

The design's rail lists event names with timestamps: `ContentStatusChanged`, `FieldUpdated`, `JournalEntryPosted`, `UserSignedIn`, `ContentCreated`.

BaryoDev/barakoCMS#229, on this same milestone, decides the opposite: the stream is internal, history is exposed only as a projected view, and a test is added that fails if any type under `Features/**` references `barakoCMS.Events.*`. Those five strings are event type names.

There is also no cross-stream feed of any kind. `useContentHistory(id)` is per-entry, and `ContentVersion.changeType` is, by its own comment in `src/types/content.ts`, "Decided server side, not the event class name", which is BaryoDev/barakoCMS#229's rule already in force.

So this panel needs a projected activity feed with its own stable vocabulary and a new endpoint, and the labels on screen become that vocabulary rather than the event types. That is a naming exercise plus server work, and it has to land before the panel can be drawn. Do not solve it by adding an event type to a response.

## The stat cards

| Card | Source today | Verdict |
| --- | --- | --- |
| Entries, 148 | `useContents().totalItems` | free |
| Published, 121, with "27 draft, 3 scheduled" | nothing | needs status counts |
| Delivery API 24h, with cache hit rate | nothing | needs a windowed metric |
| Visitors 7d with sparkline | Analytics.Umami | optional module |

`useContents` accepts page, pageSize and contentType only, so counting published, draft and scheduled entries means paging the whole collection. `MetricsSummary` in `src/hooks/use-monitoring.ts` is cumulative since process start: no 24h window, no cache-hit rate, and no p95, which the header pill also asks for (`p95 38ms · err 0.04%`). The System card wants uptime, also absent. And the Visitors card comes from an optional module, so the four-card row is three cards on a deployment without `BarakoCMS.Analytics.Umami`, a state the design does not draw.

## "Needs you"

The handoff says this is derived and needs no new endpoint. It is derived, but not from what exists today. It needs scheduled entries (`scheduledPublishAt` is on `ContentDetail`, not `ContentListItem`), drafts past an age (no status filter, no age filter), and module-reported problems, which is a mechanism that does not exist at all. Nothing lets Accounting say "this journal entry is unbalanced" or Email events say "two bounces" into a shared list.

Two ways to go: build the list from content alone for now and add module contributions later, or design the contribution mechanism first. The second is the honest one, and it is not small.

## Free on this screen

The greeting line, the tinted scheduled-publishing banner, the layout split, and the System card's health entries, which `useHealthStatus()` already returns as a dictionary.

## Done when

- The event feed decision is recorded and its endpoint exists, or the panel is cut from the first version and this issue says so.
- No stat card renders a number that is not what its label claims.
- The screen degrades correctly with Analytics.Umami absent.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.