---
description: Advanced code review for PRs across ByteLyst workspace repos
---

# Advanced Code Review

Your task is to find all potential bugs and code improvements in the code
changes. Focus on:

1. Logic errors and incorrect behavior
2. Edge cases that aren't handled
3. Null/undefined reference issues
4. Race conditions or concurrency issues
5. Security vulnerabilities
6. Improper resource management or resource leaks
7. API contract violations
8. Incorrect caching behavior, including cache staleness issues, cache
   key-related bugs, incorrect cache invalidation, and ineffective caching
9. Violations of existing code patterns or conventions
10. Duplicate code

Make sure to:

1. If you find any pre-existing bugs in the code, you should also report those
   since it's important for us maintain general code quality for the user.
2. Do NOT report issues that are speculative or low-confidence. All your
   conclusions should be based on a complete understanding of the codebase.
3. Remember that if you were given a specific git commit, it may not be checked
   out and local code states may be different.

## Scope

All code across the ByteLyst workspace repos:

- **learning_ai_common_plat** - Shared platform packages and services
  - packages/ - @bytelyst/\* shared libraries
  - services/ - platform-service, extraction-service
  - dashboards/ - admin-web, tracker-web
- **Product repos** - Individual product backends and applications
  - learning_voice_ai_agent (LysnrAI)
  - learning_multimodal_memory_agents (MindLyst)
  - learning_ai_clock (ChronoMind)
  - learning_ai_fastgap (NomGap)
  - learning_ai_flowmonk (FlowMonk)
  - learning_ai_jarvis_jr (JarvisJr)
  - learning_ai_peakpulse (PeakPulse)
  - learning_ai_notes (NoteLett)
  - learning_ai_trails (ActionTrail)
  - learning_ai_auth_app (ByteLyst SmartAuth — companion app + PRD/roadmap)
  - learning_ai_productivity_web (Productivity Tools)

## Domain Context

This is a multi-product ecosystem with shared platform services. Key architectural patterns:

- **Platform services** (Fastify 5, TypeScript ESM) provide auth, telemetry, feature flags, etc.
- **Shared packages** (@bytelyst/\*) eliminate duplication across products
- **Product backends** handle domain-specific logic (port 4010-4018)
- **Web apps** use Next.js 16 + React 19
- **Mobile apps** use native platforms (SwiftUI, Jetpack Compose, React Native)

## Style

Make sure the code follows existing conventions:

- TypeScript: ESM, strict types, Zod validation
- Services: Fastify 5 with types.ts → repository.ts → routes.ts pattern
- Cosmos DB: All documents include productId field
- No console.log in production (use req.log/app.log in Fastify, structlog in Python)
- Commit messages: type(scope): description
- Colors: Use design tokens from @bytelyst/design-tokens, never hardcode

## Target Branch

Measure against the main branch of the respective repo since that will be the branch we will merge into.

## Comments

Do not make code changes directly. Instead, suggest changes so the reviewer can evaluate them manually.

## Grammar

Do not include em dash in any outputs.

## Summary

At the end, provide a numbered list of all potential issues found. Each issue should have a number so it can be referred to easily (e.g. "3").

Also include a summary and explanation of the change of the PR or diff in general from the target branch. Use mermaid diagrams, anecdotes, and any other format you see fit.