Spaces:

sitcod3
/

BRIDGE_Modul-S_prod

Sleeping

BRIDGE_Modul-S_prod / IMPLEMENTATION_PLAN.md

BRIDGE Platform Agent

refactor(naming): modul → modules across metadata, wordmarks, headers, docs

195092e 7 days ago

5.96 kB

# IMPLEMENTATION_PLAN.md — BRIDGE Platform (Modules E & S)
> PHASE 2 deliverable. Executed autonomously per the brief's guardrails ("do not pause for confirmation between phases").
## 0. Strategy
Converge both sibling apps into ONE platform build (they share ~95 % of code and deploy to the same HF Space `sitcod3/BRIDGE_Modul-S_prod`):
- **Base = E repo (GREENTHEME-test)** — superset: ThemeContext engine, tests, Skeleton, Pricing, Stripe.
- Module S's real pages are **ported** into the platform under `src/modules/s/**` (design preserved 100 %: true-indigo palette, slate→black gradient, original UX).
- Module E's pages stay in `src/pages/**` and mount at `/modules/e/**`.
- Platform shell (Sidebar with MODULES section, per-module nav + palette, TopBar) adapts per module via the registry.
- The identical platform build is replicated into the S repo so either pipeline produces the same Space.
## 1. File-by-file change list
### NEW
| File | Purpose |
|---|---|
| `src/modules/registry.tsx` | `ModuleId`, `MODULES` registry: id, label, wordmark, accent config, tagline, nav items, icon |
| `src/modules/LaunchContext.tsx` | Launch sequencer: `startLaunch(moduleId)` bumps `seq` (re-seed), controlled **exit choreography**, `useLaunch()` |
| `src/modules/ModuleLaunchAnimation.tsx` | Random-reassembly engine (§3) |
| `src/modules/ModuleShell.tsx` | Route shell `/modules/:id`: `data-module` attr + theme override, platform chrome, launch guard → animation → `<Outlet/>` |
| `src/modules/ModuleHub.tsx` | `/` platform launcher: two real-primitive module cards + Launch buttons |
| `src/modules/PlatformSidebar.tsx` | MODULES section (2 direct-launch buttons) + active module nav |
| `src/modules/PlatformTopBar.tsx` | TopBar shell per module (module-aware API-key badge) |
| `src/modules/s/components/{StatCard,AnimatedLogo,GlassCard}.tsx` | S variants (original implementations) |
| `src/modules/s/pages/*.tsx` | 11 ported S pages (imports re-pointed; StatCard → S variant) |
### MODIFIED
| File | Change |
|---|---|
| `src/App.tsx` | New route table (§2), `LaunchProvider`, legacy redirects |
| `src/context/ThemeContext.tsx` | Add `PROD_THEME` (Module S palette); default stays mint |
| `src/index.css` | `[data-module="s"]` palette var overrides + `.bg-module-s` gradient + reduced-motion safeguard |
| `src/components/Logo.tsx` | Wordmark `ModulE`→`ModuleE`, label prop |
| `src/pages/Dashboard.tsx`, `src/pages/CampaignDetail.tsx` | 3 absolute links → `/modules/e/…` |
| `metadata.json` | name `BRIDGE Modules` + description migrated |
| `server.ts` | add `GET /api/health` |
| `README.md` | platform note |
### Tests (new)
- `src/modules/ModuleLaunchAnimation.test.tsx` — primitives render; reduced-motion instant reveal; re-seed between launches.
- `src/modules/routing.test.tsx` — `/modules/e` + `/modules/s` index pages render in-shell; hub cards; direct menu routes; legacy `/campaigns` → `/modules/e/campaigns`.
- `src/modules/naming.test.ts` — zero `Modul` stragglers in registry; `/modules/e` + `/modules/s` routes.
## 2. Route table
```
/                          ModuleHub
/modules/e                 E Dashboard (index)
/modules/e/{campaigns,campaigns/:id,leads,email-accounts,warmup,inbox,webhooks,analytics,clients,pricing,settings}
/modules/s                 S Dashboard (index)
/modules/s/{campaigns,campaigns/:id,leads,email-accounts,warmup,inbox,webhooks,analytics,clients,settings}
Legacy: /campaigns, /leads, … → replace → /modules/e/<same>      * → /
```
## 3. Launch-animation architecture (PHASE 4)
`<ModuleLaunchAnimation module mode="enter"|"exit" onComplete />`
1. **Real primitives only:** 4× `StatCard`, chart frame (GlassCard + live Recharts AreaChart), list frame (5 lead rows + StatusBadge), StatusBadge strip, KPI chips, Skeleton shimmer bar — 12 pieces in a dashboard-like grid.
2. **Random re-assembly:** `mulberry32(seed)`, `seed = Date.now() ^ hash(moduleId) ^ launchSeq` — re-seeded every launch. Per piece: off-canvas angle 0–360°, distance 240–720 px, rotation ±8–45°, scale 0.55–1.35, stagger `i*55 ms + rand(40–90) ms`, duration 2.4–3.2 s, easing `cubic-bezier(0.22, 1, 0.36, 1)`.
3. **60 fps:** transform + opacity only (motion/react WAAPI/rAF — no setTimeout chains); `will-change` during animation only; chart renders after first frame (double-rAF); pages React.lazy-preloaded on hub mount + menu hover.
4. **Reduced motion:** instant reveal, zero duration.
5. **Exit choreography:** `startLaunch` from inside a module → `exiting` → shell swaps to primitive grid with reverse-assembly (scatter outward, 0.85 s) → navigate → target enter animation. Direct URL/back bypass controlled exit.
6. **Per-module theming:** same engine; E = mint accents, S = indigo accents on slate gradient.
## 4. Menu integration (PHASE 5)
`PlatformSidebar` gains `BRIDGE MODULES` section: **Module E** (mint dot) → `/modules/e`, **Module S** (indigo dot) → `/modules/s`; active state per namespace; click = `startLaunch` + navigate (re-seeded animation); cross-launch visible in both modules; hub cards mirror the action.
## 5. Risk register & rollback
| Risk | Mitigation | Rollback |
|---|---|---|
| Tailwind v4 remap collides with S indigo | `[data-module="s"]` scoped var overrides | remove scope block |
| E absolute links break | 3 links rewritten + legacy redirects | revert pages |
| Route move breaks tests | component tests render directly; new routing tests | revert App.tsx |
| Space stale build | identical platform in both repos; 200 + bundle markers verified | HF UI rollback |
| Naming misses | naming.test + grep gate | — |
## 6. Execution order
1. ThemeContext + index.css scopes → 2. registry/LaunchContext/animation/shell/hub/chrome → 3. port S pages → 4. App.tsx routes + links → 5. server/metadata/Logo → 6. tests + tsc + build + QA (PHASE 6) → 7. replicate to S repo, push both, verify live (PHASE 7).

	# IMPLEMENTATION_PLAN.md — BRIDGE Platform (Modules E & S)

	> PHASE 2 deliverable. Executed autonomously per the brief's guardrails ("do not pause for confirmation between phases").

	## 0. Strategy

	Converge both sibling apps into ONE platform build (they share ~95 % of code and deploy to the same HF Space `sitcod3/BRIDGE_Modul-S_prod`):

	- Base = E repo (GREENTHEME-test) — superset: ThemeContext engine, tests, Skeleton, Pricing, Stripe.
	- Module S's real pages are ported into the platform under `src/modules/s/**` (design preserved 100 %: true-indigo palette, slate→black gradient, original UX).
	- Module E's pages stay in `src/pages/` and mount at `/modules/e/`.
	- Platform shell (Sidebar with MODULES section, per-module nav + palette, TopBar) adapts per module via the registry.
	- The identical platform build is replicated into the S repo so either pipeline produces the same Space.

	## 1. File-by-file change list

	### NEW
	\| File \| Purpose \|
	\|---\|---\|
	\| `src/modules/registry.tsx` \| `ModuleId`, `MODULES` registry: id, label, wordmark, accent config, tagline, nav items, icon \|
	\| `src/modules/LaunchContext.tsx` \| Launch sequencer: `startLaunch(moduleId)` bumps `seq` (re-seed), controlled exit choreography, `useLaunch()` \|
	\| `src/modules/ModuleLaunchAnimation.tsx` \| Random-reassembly engine (§3) \|
	\| `src/modules/ModuleShell.tsx` \| Route shell `/modules/:id`: `data-module` attr + theme override, platform chrome, launch guard → animation → `<Outlet/>` \|
	\| `src/modules/ModuleHub.tsx` \| `/` platform launcher: two real-primitive module cards + Launch buttons \|
	\| `src/modules/PlatformSidebar.tsx` \| MODULES section (2 direct-launch buttons) + active module nav \|
	\| `src/modules/PlatformTopBar.tsx` \| TopBar shell per module (module-aware API-key badge) \|
	\| `src/modules/s/components/{StatCard,AnimatedLogo,GlassCard}.tsx` \| S variants (original implementations) \|
	\| `src/modules/s/pages/*.tsx` \| 11 ported S pages (imports re-pointed; StatCard → S variant) \|

	### MODIFIED
	\| File \| Change \|
	\|---\|---\|
	\| `src/App.tsx` \| New route table (§2), `LaunchProvider`, legacy redirects \|
	\| `src/context/ThemeContext.tsx` \| Add `PROD_THEME` (Module S palette); default stays mint \|
	\| `src/index.css` \| `[data-module="s"]` palette var overrides + `.bg-module-s` gradient + reduced-motion safeguard \|
	\| `src/components/Logo.tsx` \| Wordmark `ModulE`→`ModuleE`, label prop \|
	\| `src/pages/Dashboard.tsx`, `src/pages/CampaignDetail.tsx` \| 3 absolute links → `/modules/e/…` \|
	\| `metadata.json` \| name `BRIDGE Modules` + description migrated \|
	\| `server.ts` \| add `GET /api/health` \|
	\| `README.md` \| platform note \|

	### Tests (new)
	- `src/modules/ModuleLaunchAnimation.test.tsx` — primitives render; reduced-motion instant reveal; re-seed between launches.
	- `src/modules/routing.test.tsx` — `/modules/e` + `/modules/s` index pages render in-shell; hub cards; direct menu routes; legacy `/campaigns` → `/modules/e/campaigns`.
	- `src/modules/naming.test.ts` — zero `Modul` stragglers in registry; `/modules/e` + `/modules/s` routes.

	## 2. Route table

	```
	/ ModuleHub
	/modules/e E Dashboard (index)
	/modules/e/{campaigns,campaigns/:id,leads,email-accounts,warmup,inbox,webhooks,analytics,clients,pricing,settings}
	/modules/s S Dashboard (index)
	/modules/s/{campaigns,campaigns/:id,leads,email-accounts,warmup,inbox,webhooks,analytics,clients,settings}
	Legacy: /campaigns, /leads, … → replace → /modules/e/<same> * → /
	```

	## 3. Launch-animation architecture (PHASE 4)

	`<ModuleLaunchAnimation module mode="enter"\|"exit" onComplete />`

	1. Real primitives only: 4× `StatCard`, chart frame (GlassCard + live Recharts AreaChart), list frame (5 lead rows + StatusBadge), StatusBadge strip, KPI chips, Skeleton shimmer bar — 12 pieces in a dashboard-like grid.
	2. Random re-assembly: `mulberry32(seed)`, `seed = Date.now() ^ hash(moduleId) ^ launchSeq` — re-seeded every launch. Per piece: off-canvas angle 0–360°, distance 240–720 px, rotation ±8–45°, scale 0.55–1.35, stagger `i*55 ms + rand(40–90) ms`, duration 2.4–3.2 s, easing `cubic-bezier(0.22, 1, 0.36, 1)`.
	3. 60 fps: transform + opacity only (motion/react WAAPI/rAF — no setTimeout chains); `will-change` during animation only; chart renders after first frame (double-rAF); pages React.lazy-preloaded on hub mount + menu hover.
	4. Reduced motion: instant reveal, zero duration.
	5. Exit choreography: `startLaunch` from inside a module → `exiting` → shell swaps to primitive grid with reverse-assembly (scatter outward, 0.85 s) → navigate → target enter animation. Direct URL/back bypass controlled exit.
	6. Per-module theming: same engine; E = mint accents, S = indigo accents on slate gradient.

	## 4. Menu integration (PHASE 5)

	`PlatformSidebar` gains `BRIDGE MODULES` section: Module E (mint dot) → `/modules/e`, Module S (indigo dot) → `/modules/s`; active state per namespace; click = `startLaunch` + navigate (re-seeded animation); cross-launch visible in both modules; hub cards mirror the action.

	## 5. Risk register & rollback

	\| Risk \| Mitigation \| Rollback \|
	\|---\|---\|---\|
	\| Tailwind v4 remap collides with S indigo \| `[data-module="s"]` scoped var overrides \| remove scope block \|
	\| E absolute links break \| 3 links rewritten + legacy redirects \| revert pages \|
	\| Route move breaks tests \| component tests render directly; new routing tests \| revert App.tsx \|
	\| Space stale build \| identical platform in both repos; 200 + bundle markers verified \| HF UI rollback \|
	\| Naming misses \| naming.test + grep gate \| — \|

	## 6. Execution order

	1. ThemeContext + index.css scopes → 2. registry/LaunchContext/animation/shell/hub/chrome → 3. port S pages → 4. App.tsx routes + links → 5. server/metadata/Logo → 6. tests + tsc + build + QA (PHASE 6) → 7. replicate to S repo, push both, verify live (PHASE 7).