diff --git a/docs/ECOSYSTEM_CONSISTENCY_AUDIT.md b/docs/ECOSYSTEM_CONSISTENCY_AUDIT.md new file mode 100644 index 00000000..c6e62145 --- /dev/null +++ b/docs/ECOSYSTEM_CONSISTENCY_AUDIT.md @@ -0,0 +1,308 @@ +# ByteLyst Ecosystem Consistency Audit + +> **Date:** 2026-03-21 +> **Scope:** All 13 repos in the ByteLyst workspace +> **Auditor:** Cascade AI + +--- + +## 1. Product Identity (`shared/product.json`) + +### Port Allocation (no collisions ✅) + +| Product | Port | Repo | +| ------------------ | ---- | ----------------------------------- | +| PeakPulse | 4010 | `learning_ai_peakpulse` | +| ChronoMind | 4011 | `learning_ai_clock` | +| JarvisJr | 4012 | `learning_ai_jarvis_jr` | +| NomGap | 4013 | `learning_ai_fastgap` | +| MindLyst | 4014 | `learning_multimodal_memory_agents` | +| LysnrAI | 4015 | `learning_voice_ai_agent` | +| NoteLett | 4016 | `learning_ai_notes` | +| FlowMonk | 4017 | `learning_ai_flowmonk` | +| ActionTrail | 4018 | `learning_ai_trails` | +| LocalMemGPT | 4019 | `learning_ai_local_memory_gpt` | +| Platform-service | 4003 | `learning_ai_common_plat` | +| Extraction-service | 4005 | `learning_ai_common_plat` | +| MCP-server | 4007 | `learning_ai_common_plat` | + +### Schema Consistency + +**Full schema (16 fields):** MindLyst, ChronoMind, JarvisJr, PeakPulse — ✅ consistent + +**Newer schema (10 fields, uses `bundleIds` + `tagline` + `appStore`):** FlowMonk, ActionTrail, LocalMemGPT, SmartAuth — ✅ consistent among themselves + +| Finding | Severity | Repos | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------- | +| **F1: NomGap product.json minimal** — only 4 fields (`productId`, `displayName`, `bundleId`, `domain`), missing `backendPort`, `version`, `licensePrefix`, `configDirName`, `envVarPrefix`, `packageName` | 🟡 Medium | `learning_ai_fastgap` | +| **F2: LysnrAI product.json missing domain/backendPort** — only 7 fields, no `domain`, `backendPort`, `description`, `cosmos`, `platforms`, `primarySurface` | 🟡 Medium | `learning_voice_ai_agent` | +| **F3: NoteLett hybrid schema** — mixes old (`bundleIdSuffix`, `packageName`) and new (`backendPort`, `domain`) but missing `version`, `cosmos`, `platforms` | 🟡 Medium | `learning_ai_notes` | +| **F4: ByteLyst Auth uses `productName` instead of `displayName`** | 🟠 Low | `learning_ai_auth_app` | +| **F5: Two schema patterns** — older repos use `bundleId` (object), newer use `bundleIds` (object). Not a bug but inconsistent. | 🟢 Info | — | + +--- + +## 2. Backend Patterns (Fastify 5 + TypeScript ESM) + +### Shared Package Adoption + +All 10 product backends have: + +- ✅ `@bytelyst/auth` — JWT utilities +- ✅ `@bytelyst/config` — env loader + product identity +- ✅ `@bytelyst/datastore` — Cosmos/memory abstraction +- ✅ `@bytelyst/errors` — typed HTTP errors +- ✅ `@bytelyst/fastify-core` — createServiceApp() factory +- ✅ `@bytelyst/fastify-auth` — auth middleware +- ✅ `@bytelyst/backend-config` — backend config helpers +- ✅ `@bytelyst/backend-flags` — feature flag server-side +- ✅ `@bytelyst/backend-telemetry` — telemetry buffer +- ✅ `product-config.ts` in `src/lib/` — all 10 backends + +### Fastify Version + +| Version | Repos | +| -------- | ---------------------------------------------------------- | +| `^5.2.1` | LysnrAI, MindLyst, ChronoMind, JarvisJr, NomGap, PeakPulse | +| `5.7.4` | FlowMonk, ActionTrail, LocalMemGPT | +| `^5.2.1` | NoteLett | + +| Finding | Severity | +| ------------------------------------------------------------------------------------------ | --------- | +| **F6: Fastify version split** — 6 repos on `^5.2.1`, 3 on `5.7.4`. Should align to latest. | 🟡 Medium | + +### Field Encryption + +| Finding | Severity | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | +| **F7: LocalMemGPT missing @bytelyst/field-encrypt** — uses local AES-256-GCM instead of shared package. Intentional (SQLite-based, local-first app) but divergent. | 🟢 Info | + +All other 9 Cosmos-based backends have `@bytelyst/field-encrypt` ✅ + +### Advanced Packages (SSE, Events, Webhooks) + +Only FlowMonk and ActionTrail have: + +- `@bytelyst/fastify-sse` — SSE streaming +- `@bytelyst/event-store` — domain event persistence +- `@bytelyst/webhook-dispatch` — outbound webhook delivery + +LocalMemGPT has `@bytelyst/fastify-sse` and `@bytelyst/llm-router` (unique). + +Other backends may need these as they mature — not a gap yet. + +--- + +## 3. Web Frontend Patterns + +### Next.js + React Versions + +| Version | Repos | +| ----------------------------------- | ---------------------------------------------------- | +| Next.js 16.1.6 + React 19.2.3 | LysnrAI, ChronoMind, JarvisJr, FlowMonk, ActionTrail | +| Next.js 16.1.6 + React 19.2.0 | NomGap, NoteLett | +| Next.js ^16.0.0 + React ^19.0.0 | MindLyst | +| **Next.js ^15.3.2 + React ^19.1.0** | **LocalMemGPT** | + +| Finding | Severity | +| ---------------------------------------------------------------------------------- | -------- | +| **F8: LocalMemGPT on Next.js 15** — all other repos on Next.js 16. Should upgrade. | 🟠 High | + +### TailwindCSS + +| Status | Repos | +| --------------------------- | -------------------------------------------------- | +| TailwindCSS v4 ✅ | LysnrAI, ChronoMind, NomGap, NoteLett, LocalMemGPT | +| **Missing TailwindCSS** | **MindLyst, FlowMonk, ActionTrail** | +| TailwindCSS v4 via JarvisJr | JarvisJr ✅ | + +| Finding | Severity | +| ---------------------------------------------------------------------------------------------------------------------------- | --------- | +| **F9: MindLyst uses vanilla CSS** — `--ml-*` props in `globals.css`, no Tailwind. Intentional per AGENTS.md ("NO Tailwind"). | 🟢 Info | +| **F10: FlowMonk + ActionTrail missing TailwindCSS** — use inline styles or basic CSS. Should add for consistency. | 🟡 Medium | + +### CSS Custom Property Namespaces + +| Namespace | Product | Status | +| -------------------- | ------------ | ------ | +| `--cm-*` | ChronoMind | ✅ | +| `--jj-*` | JarvisJr | ✅ | +| `--ng-*` | NomGap | ✅ | +| `--ml-*` | MindLyst | ✅ | +| `--fm-*` | FlowMonk | ✅ | +| `--at-*` | ActionTrail | ✅ | +| `--lmg-*` | LocalMemGPT | ✅ | +| **`--nl-*` MISSING** | **NoteLett** | ❌ | + +| Finding | Severity | +| ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| **F11: NoteLett globals.css has no `--nl-*` custom properties** — contrary to AGENTS.md which says "Theme tokens use `--nl-*` CSS custom properties". | 🟠 High | + +### Web Auth Pattern (`@bytelyst/react-auth`) + +| Has `react-auth` in web deps | Has `auth.ts` using it | +| ---------------------------- | --------------------------------------------------- | +| LysnrAI ✅ | LysnrAI uses custom auth-server pattern (dashboard) | +| ChronoMind ✅ | ChronoMind uses auth-client directly | +| NomGap ✅ | NomGap ✅ `auth.ts` uses `react-auth` | +| NoteLett ✅ | NoteLett ✅ `auth.ts` uses `react-auth` | +| ActionTrail ✅ | ActionTrail ✅ `auth.ts` uses `react-auth` | +| JarvisJr ❌ | JarvisJr — no `react-auth` dep | +| FlowMonk ❌ | FlowMonk — no `react-auth` dep | +| LocalMemGPT ❌ | LocalMemGPT — auth is optional (local-first) | + +| Finding | Severity | +| -------------------------------------------------------------------------------------------------------- | --------- | +| **F12: JarvisJr web missing `@bytelyst/react-auth`** — has kill-switch + telemetry but no auth provider. | 🟡 Medium | +| **F13: FlowMonk web missing `@bytelyst/react-auth`** — no auth provider in web. | 🟡 Medium | + +### Web `product-config.ts` + +| Finding | Severity | +| ----------------------------------------------------------------------------- | --------- | +| **F14: ChronoMind web missing `product-config.ts`** — all other webs have it. | 🟡 Medium | + +--- + +## 4. Mobile / Native Patterns + +### iOS Platform SDK (`Platform/` directory) + +| App | Platform/ dir | Status | +| ---------- | ------------------------------------------------------ | ------------------------------------- | +| LysnrAI | `mobile_app/ios/LysnrAI/Platform/` | ✅ | +| MindLyst | `mindlyst-native/iosApp/Platform/` | ✅ | +| ChronoMind | `ios/ChronoMind/Shared/Cloud/` + `Shared/Diagnostics/` | ⚠️ Different (valid for multi-target) | +| JarvisJr | `ios/JarvisJr/Platform/` | ✅ | +| PeakPulse | `ios/PeakPulse/Platform/` | ✅ | + +### Android Kotlin Platform SDK + +All 3 Android apps (ChronoMind, MindLyst, LysnrAI) have `includeBuild` for `kotlin-platform-sdk` ✅ + +JarvisJr Android exists but is Phase 4 (minimal). NomGap uses Expo (no native SDK needed). + +--- + +## 5. Design Tokens + +`@bytelyst/design-tokens` generates: + +- `tokens.css` — web CSS vars +- `tokens.ts` — TypeScript constants +- `MindLystTokens.kt` — Android tokens +- `MindLystTheme.swift` — iOS tokens + +| Finding | Severity | +| ------------------------------------------------------------------------------------------------------------------------------- | --------- | +| **F15: Only 3 webs import `@bytelyst/design-tokens`** — LysnrAI, NomGap, NoteLett. Other webs define CSS custom props manually. | 🟡 Medium | + +--- + +## 6. CI/CD & Docker + +### GitHub Actions + +| Status | Repos | +| --------------- | ------------------------------------------------------------------------------------- | +| Active `ci.yml` | ChronoMind, JarvisJr, NomGap, PeakPulse, FlowMonk, NoteLett, ActionTrail, LocalMemGPT | +| Disabled | LysnrAI (`disabled.yml`), MindLyst (`disabled.yml`) | +| No CI | ByteLyst Auth App | + +| Finding | Severity | +| --------------------------------------------------------------------------------------------------------- | --------- | +| **F16: LysnrAI + MindLyst CI disabled** — mature repos with extensive test suites should have CI enabled. | 🟡 Medium | +| **F17: ByteLyst Auth App has no CI** — no `.github/workflows/` at all. | 🟡 Medium | + +### Docker + +| Has docker-compose + Dockerfiles | Repos | +| ---------------------------------------- | ------------------------------------------------------- | +| ✅ Full stack | NomGap, NoteLett, ActionTrail, LocalMemGPT | +| docker-compose only (references sibling) | LysnrAI | +| **No Docker** | **MindLyst, ChronoMind, JarvisJr, PeakPulse, FlowMonk** | + +| Finding | Severity | +| --------------------------------------------------------------------------- | -------- | +| **F18: 5 repos have no Docker configs** — makes local/CI deployment harder. | 🟢 Info | + +--- + +## 7. Agent Documentation + +### File Presence Matrix + +| File | Present (of 13) | Missing | +| ---------------- | --------------- | ------------------------------ | +| `AGENTS.md` | 13/13 ✅ | — | +| `CLAUDE.md` | 11/13 | ActionTrail, ByteLyst Auth App | +| `.windsurfrules` | 12/13 | ByteLyst Auth App | +| `.cursorrules` | 12/13 | ByteLyst Auth App | + +| Finding | Severity | +| -------------------------------------------------------------------------- | --------- | +| **F19: ActionTrail missing CLAUDE.md** | 🟢 Low | +| **F20: ByteLyst Auth App missing CLAUDE.md, .windsurfrules, .cursorrules** | 🟡 Medium | + +--- + +## 8. Summary Scorecard + +### Critical (should fix now) + +| # | Finding | Fix | +| --- | ----------------------------------------------- | ---------------------------------------- | +| F8 | LocalMemGPT on Next.js 15 | Upgrade to Next.js 16 | +| F11 | NoteLett missing `--nl-*` CSS custom properties | Add design token CSS vars to globals.css | + +### Medium (should fix soon) + +| # | Finding | Fix | +| --- | ----------------------------------------------- | ---------------------------------------------- | +| F1 | NomGap product.json minimal (4 fields) | Add missing fields to match ecosystem standard | +| F2 | LysnrAI product.json missing domain/backendPort | Add missing fields | +| F3 | NoteLett product.json hybrid schema | Normalize to ecosystem standard | +| F6 | Fastify version split (^5.2.1 vs 5.7.4) | Align all to latest 5.7.x | +| F10 | FlowMonk + ActionTrail missing TailwindCSS | Add TailwindCSS v4 | +| F12 | JarvisJr web missing @bytelyst/react-auth | Add auth provider | +| F13 | FlowMonk web missing @bytelyst/react-auth | Add auth provider | +| F14 | ChronoMind web missing product-config.ts | Create product-config.ts | +| F15 | Only 3 webs import @bytelyst/design-tokens | Add to remaining webs | +| F16 | LysnrAI + MindLyst CI disabled | Re-enable ci.yml | +| F20 | ByteLyst Auth App missing agent docs | Add CLAUDE.md, .windsurfrules, .cursorrules | + +### Low / Informational + +| # | Finding | Notes | +| --- | ---------------------------------------------------- | ------------------------------------------- | +| F4 | Auth App uses `productName` instead of `displayName` | Minor schema inconsistency | +| F5 | Two bundleId schema patterns | `bundleId` (object) vs `bundleIds` (object) | +| F7 | LocalMemGPT uses local encryption | Intentional — SQLite-based local-first app | +| F9 | MindLyst no Tailwind | Intentional per AGENTS.md | +| F17 | Auth App no CI | Minimal repo, mostly native | +| F18 | 5 repos no Docker | Not all repos need containerization yet | +| F19 | ActionTrail missing CLAUDE.md | Low priority doc gap | + +--- + +## 9. Ecosystem-Wide Consistency Checklist + +| Dimension | Status | +| --------------------------------- | ------------------------------------------------ | +| Product ID in Cosmos docs | ✅ All backends enforce `productId` | +| Port allocation (no collisions) | ✅ 4010–4019 + 4003/4005/4007 | +| Backend Fastify 5 | ✅ All 10 backends | +| Backend `@bytelyst/fastify-core` | ✅ All 10 backends | +| Backend `@bytelyst/field-encrypt` | ✅ 9/10 (LocalMemGPT intentionally different) | +| Backend `product-config.ts` | ✅ All 10 backends | +| Web Next.js 16 | ⚠️ 8/9 (LocalMemGPT on 15) | +| Web CSS namespace `--XX-*` | ⚠️ 7/8 (NoteLett missing) | +| Web `@bytelyst/react-auth` | ⚠️ 5/8 applicable webs | +| Web `product-config.ts` | ⚠️ 7/8 (ChronoMind missing) | +| iOS `Platform/` directory | ✅ 4/5 (ChronoMind valid alternative) | +| Android kotlin-platform-sdk | ✅ All 3 Android apps | +| `AGENTS.md` | ✅ 13/13 | +| `CLAUDE.md` | ⚠️ 11/13 | +| `.windsurfrules` + `.cursorrules` | ⚠️ 12/13 | +| GitHub Actions CI | ⚠️ 8/12 active | +| `shared/product.json` | ⚠️ Inconsistent schemas across older/newer repos |