# Frontend Structure Findings During Annotation Pass

This document records concrete structure and architecture issues noticed while enriching comments in the front-end codebase. The goal is to preserve observations that repeatedly affected code readability, not to prescribe a full rewrite.

## 1. The shared query layer has become a cross-feature kitchen sink

Observed files:

- `web/src/shared/hooks/use-skill-queries.ts`
- `web/src/features/skill/use-skill-detail.ts`
- `web/src/features/namespace/use-namespace-detail.ts`

Why this stands out:

- One shared hook file currently owns search, skill detail, version reads, namespace membership, publishing, and promotion-related mutations.
- Several feature modules then re-export pieces of that shared file, which hides the real dependency direction.
- This makes the boundary between `shared` and `features` feel inverted.

Suggested direction:

- Split the file by feature slice or by backend resource area, and keep feature-facing hooks owned by their feature directories.

## 2. The router is a large centralized registry with route policy mixed into route declarations

Observed files:

- `web/src/app/router.tsx`
- `web/src/shared/components/role-guard.tsx`

Why this stands out:

- Route creation, auth guards, role checks, search validation, and lazy-loading rules are all declared in one large module.
- This works, but it increases the cost of changing one route because all route concerns are concentrated in a single file.

Suggested direction:

- Keep one router entry point, but consider splitting route definitions by area such as public, dashboard, admin, and settings.

## 3. Some pages still do too much orchestration instead of delegating to feature-level containers

Observed files:

- `web/src/pages/landing.tsx`
- `web/src/pages/search.tsx`
- `web/src/pages/skill-detail.tsx`
- `web/src/pages/dashboard.tsx`

Why this stands out:

- Several pages coordinate multiple hooks, query invalidation, local UI state, navigation rules, and derived presentation decisions.
- The page layer is therefore acting as route entry point and business container at the same time.

Suggested direction:

- Move heavier orchestration into feature containers or page-specific hooks so the page files mainly compose them.

## 4. Feature boundaries are uneven across the codebase

Observed files:

- `web/src/features/*`
- `web/src/shared/hooks/use-skill-queries.ts`
- `web/src/shared/lib/*`

Why this stands out:

- Some concerns are organized cleanly by feature, while others remain in shared folders even though they are domain-specific.
- This makes it harder to predict where new logic should live.

Suggested direction:

- Tighten the rule for what qualifies as `shared`: generic UI, generic hooks, and framework glue should stay there; business-specific query logic should usually live under `features`.

## 5. Runtime configuration bootstrapping relies on a global window contract

Observed files:

- `web/src/bootstrap.ts`
- `web/src/api/client.ts`
- `web/public/runtime-config.js`

Why this stands out:

- The current approach is pragmatic for deploy-time configuration, but it couples startup and API behavior to a mutable global object on `window`.
- That contract is easy to miss because its definition is spread across bootstrap and API code.

Suggested direction:

- Keep the mechanism if deploy-time injection is required, but document the lifecycle clearly or wrap it behind a dedicated runtime-config module.

## 6. Some feature modules are only thin re-export layers over shared hooks

Observed files:

- `web/src/features/skill/use-skill-detail.ts`
- `web/src/features/namespace/use-namespace-detail.ts`
- `web/src/features/namespace/use-namespace-members.ts`
- `web/src/features/publish/use-publish-skill.ts`

Why this stands out:

- These files preserve a feature-oriented import path, but they do not own the actual logic.
- The real behavior still lives in shared modules, which weakens the meaning of the feature boundary.

Suggested direction:

- Either move the implementation into the feature modules or import the shared hooks directly; keeping both layers long term adds indirection without much value.

## 7. Some generic dashboard widgets still contain workflow-specific routing rules

Observed files:

- `web/src/features/governance/governance-inbox.tsx`
- `web/src/features/governance/governance-notifications.tsx`

Why this stands out:

- These components look presentation-oriented, but they still know how review, promotion, report, and skill routes map onto dashboard URLs.
- That means route policy is now split between the central router and a few feature widgets.

Suggested direction:

- Consider moving item-to-route resolution into a dedicated governance navigation helper or feature hook, so the visual components stay closer to pure rendering.