agent-ecosystem/src/features/recent-projects/README.md

Recent Projects Feature

recent-projects is the full cross-process reference for docs/FEATURE_ARCHITECTURE_STANDARD.md. Use it as the local example when a feature owns contracts, pure business rules, runtime composition, transport adapters, preload bridging, and renderer UI.

Read this with:

• Feature root guide
• Feature-local agent guidance

Feature Shape

src/features/recent-projects/
  contracts/
  core/
    domain/
    application/
  main/
    composition/
    adapters/
      input/
      output/
    infrastructure/
  preload/
  renderer/

This feature intentionally does not have a root index.ts. Production callers enter through the layer-specific public entrypoints:

• contracts/index.ts for DTOs, channels, API fragments, and payload normalization
• main/index.ts for main-process registration and composition
• preload/index.ts for bridge creation
• renderer/index.ts for renderer-owned UI and public renderer utilities

Layer Examples

• core/domain/policies/mergeRecentProjectCandidates.ts owns provider-agnostic merge policy and stays pure
• core/application/use-cases/ListDashboardRecentProjectsUseCase.ts orchestrates ports and response models without importing runtime details
• main/composition/createRecentProjectsFeature.ts wires infrastructure, adapters, ports, and use cases for the main process
• main/adapters/input/ipc/registerRecentProjectsIpc.ts and main/adapters/input/http/registerRecentProjectsHttp.ts translate transport requests into feature calls
• main/adapters/output/sources/* adapts provider/runtime data into the core model
• main/infrastructure/cache/InMemoryRecentProjectsCache.ts and main/infrastructure/identity/* keep runtime-specific helpers out of core/
• preload/createRecentProjectsBridge.ts exposes the feature API fragment to the renderer
• renderer/hooks/useRecentProjectsSection.ts coordinates renderer interaction and data access
• renderer/ui/RecentProjectsSection.tsx keeps the visual component focused on rendering and callbacks

How To Extend It

When adding another source or provider:

• add or reuse a port in core/application/ports/
• keep provider-specific parsing in main/adapters/output/ or main/infrastructure/
• keep merge, ordering, dedupe, and selection rules in core/domain/
• wire the new dependency in main/composition/createRecentProjectsFeature.ts
• add focused tests beside the layer that owns the behavior

When adding another transport:

• put shared request/response shape in contracts/
• implement the input adapter under main/adapters/input/
• keep handler registration out of core/
• expose only the stable surface from main/index.ts

When changing renderer behavior:

• keep data fetching and app API calls in hooks or renderer adapters
• keep UI components presentational
• transform DTOs into view models before they reach reusable UI where practical
• update renderer utility tests when sorting, navigation, active-team state, or client cache behavior changes

When updating this reference:

• keep examples tied to real files in this feature
• update this README when public entrypoints or intended extension paths change
• leave cross-feature architecture wording in the shared standard

Test Map

Reference tests live under test/features/recent-projects/:

• contracts/ covers payload normalization
• core/domain/ covers merge policy
• core/application/ covers use-case orchestration through ports
• main/adapters/output/ and main/infrastructure/ cover provider and runtime integration boundaries with fakes
• renderer/adapters/ and renderer/utils/ cover view-model mapping and interaction helpers

For new medium or large features, this test shape is a good starting point: domain rules first, application use cases second, then focused adapter and renderer utility coverage for behavior that can break user workflows.