bytelyst/learning_ai_common_plat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add ecosystem consistency audit — 20 findings across 13 repos

Browse Source
This commit is contained in:
saravanakumardb1 2026-03-21 20:21:06 -07:00
parent dba594d4eb
commit f9fa583cae
1 changed files with 308 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

308
docs/ECOSYSTEM_CONSISTENCY_AUDIT.md Normal file
View File

@ -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 |