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

docs(architecture): clarify platform boundary

Browse Source
This commit is contained in:
Saravana Achu Mac 2026-05-05 09:17:02 -07:00
parent f7a695e996
commit 8798fdd2e9
3 changed files with 16 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
AGENTS.md
View File

@ -237,6 +237,13 @@ learning_ai_notes/
## 5. Key Design Decisions
### Product/Common Platform Boundary
- Keep NoteLett domain logic product-local: notes, workspaces, relationships, tasks, artifacts, agent action audit trails, saved views, prompt templates/runners, intake, sharing/collaboration, versions, Palace memory/KG UX, and NoteLett-specific web/mobile workflows.
- Use `../learning_ai/learning_ai_common_plat` for platform concerns: auth/session primitives, API clients, datastore/Cosmos abstractions, errors, config/logging conventions, telemetry, diagnostics, feature flags, kill switch, blob, extraction, design tokens, shared UI primitives where appropriate, MCP server integration, webhook dispatch, encryption helpers, and automation scripts.
- Do not move notes-specific contracts or behavior into common platform unless another ByteLyst product has a concrete reuse need.
- Do not add repo-local substitutes for platform services or packages that already exist in common platform.
### MCP Tool Architecture
- 8 MCP tools: list, get, search, create_draft, update, link_notes, extract_tasks, attach_artifact
- Every write tool records an agent action audit trail

8
README.md
View File

@ -50,6 +50,14 @@ curl -sf http://localhost:4016/api/bootstrap
| **Extraction** | extraction-service (shared) | 4005 |
| **MCP** | mcp-server (shared) | 4007 |
## Architecture Boundaries
NoteLett keeps product-local domain behavior in this repo: note/workspace CRUD, relationships, tasks, artifacts, agent action audit trails, saved views, prompt templates/runners, intake rules/jobs, note sharing/collaboration, version history, Palace memory/KG UX, and all NoteLett-specific web/mobile workflows.
Common-platform responsibilities come from `../learning_ai/learning_ai_common_plat`: auth/session primitives, API clients, datastore/Cosmos abstractions, shared error/config/logging conventions, telemetry, diagnostics, feature flags, kill switch, blob access, extraction-service clients, design tokens, shared UI primitives where appropriate, MCP server integration, webhook dispatch, encryption helpers, and cross-repo automation scripts.
Do not move NoteLett-specific notes logic into common platform unless another product has a concrete reuse need. Do not create repo-local substitutes for platform concerns already covered by `@bytelyst/*` packages or platform services.
## Key Features
- **Backend modules**: notes, workspaces, relationships, tasks, artifacts, agent actions, saved views, Smart Actions, intake, collaborators, shares, versions, Palace, and ecosystem import routes

2
docs/PRODUCTION_READINESS_HANDOFF_ROADMAP.md
View File

@ -110,7 +110,7 @@ Goal: remove roadmap drift so agents do not chase already completed or obsolete
- [x] **P1.2** Update `AGENTS.md` with current module list, endpoint list, test counts, route modules, containers, shared packages, and verification commands. Commit: `99efad8`; Verified: `git diff --check`; AGENTS now points at the active production-readiness roadmap, the correct common-platform path, current backend/web/mobile modules, 14 API route modules, expanded endpoint/container lists, current test inventory, lint/E2E commands, and the May 5 baseline failure note.
- [x] **P1.3** Update `README.md` quick start with required common-platform services, auth expectations, Docker path, local memory mode, and production env requirements. Commit: `014b098`; Verified: `git diff --check`; README now documents the local common-platform checkout, platform/extraction/MCP ports, memory-mode command, Docker compose smoke path, auth expectations, production env requirements, and current baseline caveat.
- [x] **P1.4** Mark stale `docs/GAP_ANALYSIS.md`, `docs/AGENT_TASK_ROADMAP.md`, and older reuse roadmaps as historical or reconcile their open items with this roadmap. Commit: `6307c60`; Verified: `git diff --check`; added historical/superseded banners to the March gap analysis, agent task roadmap, architecture review, and reuse alignment roadmaps, including a correction that the common-platform backend package-source blocker is stale.
- [ ] **P1.5** Add a concise architecture boundary section: product-local NoteLett logic versus common platform responsibilities. Commit:
- [x] **P1.5** Add a concise architecture boundary section: product-local NoteLett logic versus common platform responsibilities. Commit: `pending`; Verified: `git diff --check`; README and AGENTS now document product-local NoteLett domain ownership versus common-platform responsibilities and warn against premature extraction or repo-local platform substitutes.
Acceptance criteria:
- No active roadmap says common-platform packages are missing when they exist.