7bd14054d4
Review findings addressed (20+ issues): Structure additions: - Target Users section with 5 personas (solo dev, tinkerer, privacy pro, writer, power user) - Non-Goals section (8 explicit out-of-scope items for v4) - Risks & Mitigations table (10 risks with impact/likelihood/mitigation) - New API Routes section (4 new routes with security notes) - Settings Expansion section (full tree: General, Router, Models, Input, Tasks, Data, About) - New Dependencies table (idb ~1KB, fuse.js ~6KB, cron-parser ~3KB) - Error Handling appendix (12 edge cases with expected behavior) Data model fixes: - Conversation/Message split into separate IndexedDB stores (scalability) - Message gets conversationId FK, promptTokens field, size/language on Attachment - Design decision note explaining why messages are stored separately Feature spec improvements: - 3.1 Conversations: context window management (token bar, auto-summarize at 80/95%) - 3.2 Quick Actions: expanded Cmd+K palette spec (5 result types, ranking) - 3.3 Agents: tools marked v4 vs v5, duplicate-from-builtin, unlink on delete - 3.4 Model Router: full resolveModel() with 4-level fallback chain + availability - 3.5 Multi-Modal: attachment size limits, Whisper error handling - 3.6 Response: hover-only action bars, rating aggregation per task type - 3.7 Cron: built-in templates table, runtime constraints, security (execFile) - 3.8 Orchestration: full data model, chain/race/vote UI specs, step limits - 3.9 Projects: system context detail, project stats, unlink behavior Acceptance criteria added to ALL 9 features (was missing on 5). Competitive analysis expanded with local competitors (Open WebUI, LM Studio, Jan.ai). Success metrics improved with measurement methodology and rationale. Open questions restructured as decision table with recommendations. IndexedDB schema with explicit indexes and compound keys. Migration strategy: 7-step v3→v4 with safety (no delete until confirmed). 681 lines → 1149 lines (+69% content) |
||
|---|---|---|
| __LOCAL_LLMs | ||
| .changeset | ||
| .github | ||
| .husky | ||
| .windsurf/workflows | ||
| AI.dev/SKILLS | ||
| docs | ||
| packages | ||
| scripts | ||
| services | ||
| .aider.conf.yml | ||
| .clinerules | ||
| .cursorrules | ||
| .editorconfig | ||
| .env.example | ||
| .gitignore | ||
| .nvmrc | ||
| .prettierrc | ||
| .windsurfrules | ||
| AGENTS.md | ||
| CLAUDE.md | ||
| docker-compose.yml | ||
| eslint.config.js | ||
| MANUAL_CI.md | ||
| package.json | ||
| pnpm-lock.yaml | ||
| pnpm-workspace.yaml | ||
| quick-check.sh | ||
| README.md | ||
| tsconfig.base.json | ||
| vitest.config.ts | ||
ByteLyst Common Platform
Shared packages and microservices for ByteLyst ecosystem products.
⚠️ GitHub Actions Temporarily Disabled
CI/CD is currently disabled due to billing issues. Please run manual quality checks before merging:
- See MANUAL_CI.md for instructions
- Use
.windsurf/workflows/production-readiness.mdfor comprehensive checks
Quick Start
# Install dependencies
pnpm install
# Build all packages + services
pnpm build
# Quick quality check (5 min) - run before pushing!
./quick-check.sh
# Run all tests (165 total across packages + services)
pnpm test
# Type-check all packages
pnpm typecheck
# Run a specific service in dev mode
pnpm --filter @lysnrai/platform-service dev
Repository Structure
learning_ai_common_plat/
├── packages/ # Shared libraries (@bytelyst/*)
│ ├── errors/ # Typed HTTP service errors (400–429)
│ ├── cosmos/ # Azure Cosmos DB client + container registry
│ ├── config/ # Zod env loader + product identity
│ ├── auth/ # JWT, middleware, password hashing
│ ├── api-client/ # Configurable fetch wrapper
│ ├── react-auth/ # React auth context factory
│ └── design-tokens/ # Cross-platform tokens (JSON → CSS/TS/Kotlin/Swift)
├── services/ # Product-agnostic microservices
│ ├── platform-service/ # Auth, audit, flags, notifications, blob (port 4003)
│ ├── billing-service/ # Subscriptions, Stripe, usage, licenses (port 4002)
│ ├── growth-service/ # Invitations, referrals, promos (port 4001)
│ ├── tracker-service/ # Items, comments, votes, public roadmap (port 4004)
│ └── monitoring/ # Loki + Grafana config, health-check
└── docs/ # Architecture docs, roadmap, analysis
Shared Libraries
| Package | Description | Peer Dependencies |
|---|---|---|
@bytelyst/errors |
Typed HTTP service errors (400–429) | — |
@bytelyst/logger |
Structured logger factory for services/dashboards | — |
@bytelyst/cosmos |
Azure Cosmos DB client singleton + container registry | @azure/cosmos |
@bytelyst/blob |
Azure Blob Storage helpers + SAS URL generation | @azure/storage-blob |
@bytelyst/config |
Zod-based env config loader + product identity | zod |
@bytelyst/auth |
JWT utilities, auth middleware, password hashing | jose, bcryptjs |
@bytelyst/fastify-core |
Fastify service bootstrap (request-id, /health, errors) | fastify |
@bytelyst/api-client |
Configurable fetch wrapper with auth token injection | — |
@bytelyst/react-auth |
React auth context factory (typed provider + hook) | react |
@bytelyst/design-tokens |
Cross-platform design tokens (JSON → CSS/TS/Kotlin/Swift) | — |
@bytelyst/extraction |
Extraction service client + shared types | @bytelyst/api-client |
@bytelyst/testing |
Shared test helpers (Fastify inject, schema asserts) | vitest |
@bytelyst/monitoring |
Health-check aggregation utilities | — |
Shared Services
| Service | Port | Description | Tests |
|---|---|---|---|
platform-service |
4003 | Auth, audit, feature flags, notifications, blob storage | 55 |
billing-service |
4002 | Subscriptions, Stripe webhooks, usage tracking, licenses, plans | 32 |
growth-service |
4001 | Invitations, referrals, promo codes | 33 |
tracker-service |
4004 | Feature requests, bugs, tasks, public roadmap | 45 |
monitoring |
— | Loki + Grafana dashboards, health-check script | — |
All services are product-agnostic — every Cosmos document includes a productId field, so a single deployment serves LysnrAI, MindLyst, or any future product.
Quick Start
# Install dependencies
pnpm install
# Build all packages + services
pnpm build
# Quick quality check (5 min) - run before pushing!
./quick-check.sh
# Run all tests (165 total across packages + services)
pnpm test
# Type-check all packages
pnpm typecheck
# Run a specific service in dev mode
pnpm --filter @lysnrai/platform-service dev
Consuming Libraries from Product Repos
During development, use file: references in consumer package.json:
// From a Next.js dashboard at repo root (2 levels up):
"@bytelyst/errors": "file:../../learning_ai_common_plat/packages/errors"
// From MindLyst web (3 levels up — inside mindlyst-native/web/):
"@bytelyst/design-tokens": "file:../../../learning_ai_common_plat/packages/design-tokens"
All repos must be cloned side-by-side under the same parent directory.
Design Tokens
Generate platform-specific token files from the canonical JSON:
cd packages/design-tokens
pnpm generate
Outputs in packages/design-tokens/generated/:
tokens.css— CSS custom properties (--ml-*)tokens.ts— TypeScript constantsMindLystTokens.kt— Kotlin object for KMPMindLystTheme.swift— Swift structs for SwiftUI
Roadmap
See docs/ROADMAP.md for the full phased extraction plan.