3a36fe8eaa
* chore: setup spec-kit * chore: add feature-architecture specs * feat(web): implement feature architecture standard with walletconnect migration - Add ESLint no-restricted-imports rule to enforce feature boundaries - Create feature architecture documentation at apps/web/docs/feature-architecture.md - Migrate walletconnect feature as reference implementation: - Add public API barrel file (index.ts) with lazy-loaded default export - Extract types to types.ts - Create feature flag hook (useIsWalletConnectEnabled) - Reorganize store into store/ directory - Move WalletConnectContext to components/WalletConnectContext/ - Update all internal imports to relative paths - Update all external imports to use public API - Fix affected test files (Header, useSafeWalletProvider) - Update AGENTS.md with feature architecture reference * fix prettier --------- Co-authored-by: katspaugh <[email protected]> Co-authored-by: Hanzo Dev <[email protected]>
5.6 KiB
Implementation Plan: Feature Architecture Standard
Branch: 001-feature-architecture | Date: 2026-01-08 | Spec: spec.md
Input: Feature specification from /specs/001-feature-architecture/spec.md
Summary
Establish a standard feature architecture pattern for the Safe{Wallet} web application that enforces feature isolation through a consistent folder structure, typed interfaces, feature flags (useHasFeature), and lazy loading. The walletconnect feature will be migrated first as a reference implementation, learnings documented, then all 21 features migrated to the new standard. ESLint rules will enforce compliance (warnings during migration, errors after completion).
Technical Context
Language/Version: TypeScript 5.x (Next.js 14.x)
Primary Dependencies: Next.js (dynamic imports), ESLint (import restrictions), Redux Toolkit (state management)
Storage: N/A (architecture pattern, no new data storage)
Testing: Jest + React Testing Library (unit tests), Cypress (E2E)
Target Platform: Web (Next.js SSR/CSR)
Project Type: Web application (existing monorepo)
Performance Goals: Zero bytes loaded for disabled features; code splitting verified via bundle analysis
Constraints: Must preserve all existing feature functionality; ESLint rules must be compatible with existing configuration
Scale/Scope: 21 existing features in apps/web/src/features/; ~50+ files affected per feature migration
Constitution Check
GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.
| Principle | Status | Notes |
|---|---|---|
| I. Monorepo Unity | ✅ PASS | Feature architecture is web-only; no impact on mobile or shared packages |
| II. Type Safety | ✅ PASS | All feature interfaces will be strongly typed; types.ts required per feature |
| III. Test-First Development | ✅ PASS | Existing tests preserved; new patterns demonstrated via walletconnect reference |
| IV. Design System Compliance | ✅ PASS | No UI changes; feature structure only affects code organization |
| V. Safe-Specific Security | ✅ PASS | No security-critical changes; feature isolation improves security posture |
Architecture Constraints Check:
- ✅ Features remain in
src/features/as required - ✅ Each feature behind feature flag (CGW API chain configs)
- ✅ ESLint enforcement aligns with workflow enforcement principle
All gates pass. Proceeding to Phase 0.
Project Structure
Documentation (this feature)
specs/001-feature-architecture/
├── plan.md # This file
├── research.md # Phase 0 output - ESLint patterns, lazy loading best practices
├── data-model.md # Phase 1 output - Feature module structure definition
├── quickstart.md # Phase 1 output - How to create/migrate a feature
├── contracts/ # Phase 1 output - Feature public API interfaces
└── tasks.md # Phase 2 output (/speckit.tasks command)
Source Code (repository root)
apps/web/
├── src/
│ ├── features/
│ │ ├── walletconnect/ # Reference implementation (P2)
│ │ │ ├── index.ts # Public API barrel file
│ │ │ ├── types.ts # Feature type definitions
│ │ │ ├── constants.ts # Feature constants
│ │ │ ├── components/
│ │ │ │ ├── index.ts # Component exports
│ │ │ │ └── [ComponentName]/
│ │ │ ├── hooks/
│ │ │ │ ├── index.ts # Hook exports
│ │ │ │ └── useIsWalletConnectEnabled.ts
│ │ │ ├── services/
│ │ │ │ └── index.ts # Service exports
│ │ │ └── store/
│ │ │ └── index.ts # Redux slice exports (if any)
│ │ └── [other-features]/ # 20 more features following same pattern
│ └── ...
├── docs/
│ └── feature-architecture.md # Feature pattern documentation (P1)
└── eslint.config.mjs # ESLint rules for import restrictions
# Root level
├── AGENTS.md # Updated with feature architecture reference
└── specs/001-feature-architecture/
└── migration-learnings.md # Post-walletconnect learnings (P4)
Structure Decision: Web application monorepo pattern. Features organized under apps/web/src/features/ with standardized internal structure. ESLint rules added to existing flat config. Documentation in apps/web/docs/.
Complexity Tracking
No constitution violations requiring justification. All changes align with existing patterns and principles.
| Consideration | Decision | Rationale |
|---|---|---|
| ESLint plugin choice | eslint-plugin-import or no-restricted-imports |
Native ESLint rule preferred to avoid new dependency |
| Migration approach | Phased (walletconnect first) | Reduces risk, captures learnings before full rollout |
| Feature flag requirement | Existing FEATURES enum sufficient | No new infrastructure needed |