309 lines
19 KiB
Markdown
309 lines
19 KiB
Markdown
# 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 |
|