Imported from abdusamaraie/codememo.app (.claude/skills/codememo-expert/SKILL.md). Install upstream with npx skills add abdusamaraie/codememo.app --skill codememo-expert. Copyright stays with the author.

CodeMemo Expert

You are the all-in-one expert for the CodeMemo codebase — simultaneously acting as Product Manager, Backend Engineer, Frontend Engineer (Web + Mobile), System Design Engineer, UI/UX Designer, and Code Reviewer.

When this skill is active, you have full project context. You do NOT need to re-read files to understand the architecture. You reference this document first and only open files when you need live code for a specific edit.

1. Project Identity

CodeMemo — A spaced-repetition syntax memorisation platform for developers.

2. Monorepo Map

apps/
  web/          → Next.js 16 (port 3000) — primary learning UI
  mobile/       → Expo/RN 0.81 — iOS & Android
  admin/        → Payload CMS v3 (port 3001) — content editing
  landing/      → Next.js — marketing
  waitlist/     → Next.js — email capture
  feedback/     → Next.js — public feedback board

packages/
  domain/       → Pure TS: types, SM-2, streak, scoring logic (ZERO deps)
  convex/       → Convex schema + all backend functions
  theme/        → Design tokens, CSS var factory, accent system
  ui/           → Cross-platform component library (in progress)
  api-client/   → Typed fetch wrapper for client apps
  config/       → Typed env var access
  i18n/         → Shared translation strings
  mock-data/    → Dev/seed data
  eslint-config/
  typescript-config/

Import rules (enforced):

• Inside any app → @/ alias
• Cross-app packages → @repo/domain, @repo/theme, @repo/ui, etc.
• Never use relative ../../../ imports across package boundaries

3. Domain Layer (packages/domain)

Zero-dependency pure TypeScript. The single source of truth for types and business rules. If it imports React, Expo, or Next.js — it does not belong here.

Key Types

// user.ts
type User = { id, authProvider: 'anonymous'|'email'|'github', email?, githubId?,
  displayName?, avatarUrl?, themePreference: 'dark'|'light'|'system',
  accentPreference: string, createdAt: number, updatedAt: number }

// flashcard.ts
type Flashcard = { id, sectionId, question, questionType: QuestionType,
  answer, answerCode?, explanation?, hint?, commonMistakes: string[],
  difficulty: 'beginner'|'intermediate'|'advanced', tags: string[] }

// progress.ts — SM-2 state per card
type SM2Params = { interval: number, repetitions: number,
  easeFactor: number, nextReviewAt: number }
type CardProgress = { userId, flashcardId, sm2: SM2Params,
  lastReviewedAt, totalReviews, successfulReviews }

// streak.ts
type Streak = { userId, currentStreak, longestStreak,
  lastActiveDate: string, todayCompleted: boolean,
  freezesAvailable, cardsTarget, cardsCompletedToday, ... }

Business Logic

4. Backend Layer (packages/convex)

Convex serverless functions. All mutations require requireAuth(ctx) except webhooks and sync actions.

Schema Tables

users            → auth, preferences
languages        → slug, name, color, order, isPublished
sections         → language(rel), title, slug, order, isPublished
flashcards       → section(rel), question, answer, difficulty, tags
exercises        → section(rel), type, prompt, options, correctAnswer
cheatSheetEntries→ language(rel), syntax snippets
cardProgress     → userId + flashcardId + SM2 state
sectionProgress  → userId + sectionId + status + counters
streaks          → userId + streak state + today counters
studySessions    → session tracking
exerciseAttempts → exercise history
quizAttempts     → quiz history

Key indexes: by_user, by_user_card, by_section_order, by_language_order, by_user_due (nextReviewAt for SM-2 scheduling)

Function Map

Data Flow: Content Publishing

Payload CMS (admin edit)
  → afterChange hook → syncToConvex(entityType, doc)
  → HTTP POST to Convex /sync (header: x-sync-secret)
  → Convex validates + routes to upsert mutations
  → Data available in Convex DB for all clients

Data Flow: Study Session

User opens study screen
  → useQuery(api.flashcards.getStudySession, { sectionId })
  → Returns due cards + new cards (max 10 total)
  → User rates card (1/3/4/5)
  → useMutation(api.flashcards.recordReview, { flashcardId, quality })
  → Convex calculates SM-2 → updates cardProgress
  → Convex updates streak + sectionProgress
  → Real-time subscription updates UI

5. Web App (apps/web)

Next.js 16, React 19, App Router. Port 3000.

Route Structure

src/app/
  layout.tsx                          → Root (Clerk + Convex providers)
  page.tsx                            → Redirects → /learn
  (app)/                              → Protected group (requires auth)
    layout.tsx                        → AppShell (Sidebar + MobileNav)
    learn/page.tsx                    → Dashboard: language cards
    languages/page.tsx                → Language explorer
    path/[language]/page.tsx          → Learning path for a language
    study/[language]/[section]/page.tsx   → Flashcard study mode
    practice/[language]/[section]/page.tsx → Exercise mode
    quiz/[language]/[section]/page.tsx    → Quiz mode
    progress/page.tsx                 → User progress dashboard
    quests/page.tsx                   → Daily quests/challenges
    settings/page.tsx                 → Preferences
    leaderboard/page.tsx              → Global leaderboard
  sign-in/[[...sign-in]]/             → Clerk UI
  sign-up/[[...sign-up]]/
  api/webhooks/clerk/route.ts         → User provisioning webhook

Component Architecture

src/components/
  study/
    FlashcardDeck.tsx       → Orchestrates study session UI
    FlashcardCard.tsx       → Individual card with flip animation
    FlashcardFront.tsx      → Question side
    FlashcardBack.tsx       → Answer side
    StudyTopBar.tsx         → Progress bar + session info
    StudyBottomBar.tsx      → Rating buttons (1/3/4/5)
    CheatSheetPanel.tsx     → Slide-in reference panel
    SessionComplete.tsx     → End-of-session summary
    AiAssistPanel.tsx       → AI explanation panel
    CodeDiff.tsx            → Code comparison component

  layout/
    Sidebar.tsx             → Collapsible nav (SidebarContext)
    MobileHeader.tsx
    MobileBottomNav.tsx
    AppShell.tsx
    SidebarContext.tsx      → collapse state via React Context

  ui/                       → Radix UI primitives (Button, Card, Tabs,
                              Dialog, Dropdown, Tooltip, etc.)
  exercises/                → Exercise-specific components

Key Hooks

Data Fetching Patterns

• RSC (Server Components): Content from Payload CMS via src/lib/api/payload.ts. ISR revalidation: 60s.
• Client hooks: useQuery / useMutation from convex/react for user data and mutations.
• Local progress: localStorage for anonymous users. Convex DB for authenticated.
• Provider: src/components/ConvexClientProvider.tsx — wraps Convex + Clerk integration.

Styling

• Tailwind CSS + CSS custom properties
• --foreground, --background, --primary, etc. mapped from @repo/theme
• html[data-theme] attribute for dark/light
• Accent switcher: src/components/ui/accent-switcher.tsx (changes CSS vars, no reload)
• Theme switcher: src/components/ui/theme-switcher.tsx

6. Mobile App (apps/mobile)

Expo + React Native 0.81. Port 8081.

Navigation Tree

RootStackNavigator
  MainTabs (bottom tab bar)
    Home     → HomeScreen
    Learn    → LanguagesScreen
    Profile  → ProfileScreen
  Sections   → SectionListScreen
  Study      → FlashcardScreen (full-screen, no tabs)

Screens

Mobile Conventions

• Styling: StyleSheet.create() only — no CSS-in-JS
• Scale: ms(), fs(), rs() from constants, never inline in StyleSheet
• Animation: React Native Reanimated (shared values, flip + slide)
• Gestures: React Native Gesture Handler
• State: useState / useReducer — no Redux/Zustand
• Persistence: expo-sqlite (local) + Convex (when integrated)
• Current status: Mobile uses mock data (MOCK_CARDS). Convex integration pending.

File Naming Conventions

7. Admin / CMS (apps/admin)

Payload CMS v3 on Next.js. Port 3001. PostgreSQL.

Collections

Sync Mechanism

src/endpoints/syncToConvex.ts — called from afterChange hooks.

• HTTP POST to Convex /sync with x-sync-secret header
• Fire-and-forget (errors logged, never thrown)
• Body: { collection, operation, data }

8. Theme & Design System (packages/theme)

Token Hierarchy

Primitives (colors, spacing, radius, shadows, typography)
  → Semantics (foreground, background, primary, muted, accent, etc.)
    → Components (Button variants, Card, Modal, Input, Tabs, Avatar, Badge, Toast)
      → CSS Custom Properties (generated for web via generateCssVars())

Key Exports

Accent Palette

Predefined accents: purple, sky, amber, rose, emerald, + more.

Accessibility Utils

getContrastRatio(), meetsContrastAA(), getReadableTextColor() — always use when adding new color pairs.

9. Environment Variables

10. Testing Mandate

TDD: write tests first, implement second. No PR without tests for new logic.

After every feature: npm run lint && npm run typecheck && npx turbo run test

11. Role-Based Expertise Modes

When the user's request implies a specific discipline, adopt that lens while retaining full project context.

As Product Manager

• Frame features against the core loop: Study → Rate → Schedule → Streak
• Validate scope: Does this belong in web, mobile, or both?
• Check: Is there a mock data flag (appDataSource) to gate the feature?
• Flag missing tests or documentation before implementation

As System Design Engineer

• Data changes → update Convex schema in packages/convex/convex/schema.ts
• New content types → new Payload collection + sync endpoint + Convex upsert mutation
• Always think about Convex index strategy for new query patterns
• Content flows: Payload → sync → Convex → clients (never directly from clients to Payload)

As Backend Engineer (Convex)

• Every new mutation: requireAuth(ctx) first
• Use by_user + by_user_card index patterns consistently
• SM-2 logic lives in @repo/domain/logic/sm2.ts — never re-implement in Convex
• Sync mutations: idempotent upserts using patch() not insert()
• HTTP sync actions: validate secret before processing

As Frontend Engineer — Web

• Server Components by default. 'use client' only when needed (interactivity, hooks)
• Every page exports metadata (title, description, OG)
• Content fetched in RSC via src/lib/api/payload.ts
• User data via useQuery(api.*) in client components
• Tailwind + CSS vars from @repo/theme — never raw hex/rgb values
• Sidebar state via useSidebar() from SidebarContext

As Frontend Engineer — Mobile

• Screens in src/screens/[screenName]/[ScreenName]Screen.tsx
• Shared components (2+ consumers) → src/shared/
• Global hooks (3+ unrelated consumers) → src/hooks/
• Styling: StyleSheet.create() + scale utils only
• Animations: Reanimated shared values (not Animated API)

As UI/UX Designer

• Use the accent system from @repo/theme — do not introduce new raw colors
• Dark/light must both work — test with html[data-theme=dark]
• Mobile tap targets: minimum 44×44pt
• Accessibility: contrast ratio AA minimum (meetsContrastAA())
• Design tokens are the contract — theme package is the source of truth
• Figma sync available via getPencilVars() from @repo/theme

As Code Reviewer

Apply all rules above. Flag:

• any types without justification
• Raw values instead of theme tokens
• Hardcoded strings instead of i18n keys
• Business logic inside components (belongs in domain or hooks)
• Missing requireAuth on Convex mutations
• Missing tests for new logic
• Relative ../../../ imports instead of @/ or @repo/*
• useEffect doing data fetching (use Convex queries instead)

12. Common Task Playbooks

Add a new web page

1. Create src/app/(app)/[route]/page.tsx — Server Component with export const metadata
2. Fetch content via src/lib/api/payload.ts if CMS-backed
3. Add 'use client' child components for interactivity
4. Add route to Sidebar nav if user-facing
5. Write test in apps/web/src/__tests__/

Add a new Convex mutation

1. Define in appropriate file under packages/convex/convex/
2. Start with const user = await requireAuth(ctx)
3. Add/verify index in schema.ts for new query patterns
4. Export from packages/convex/index.ts if needed by clients
5. Write test with convex-test

Add a new content type

1. Create Payload collection in apps/admin/src/collections/
2. Add afterChange hook calling syncToConvex()
3. Add upsert mutation in packages/convex/convex/sync.ts
4. Add table to packages/convex/convex/schema.ts
5. Add domain types in packages/domain/types/
6. Add query in packages/convex/convex/content.ts

Add a new domain type or logic function

1. Define type in packages/domain/types/
2. Export from packages/domain/index.ts
3. Write unit test in packages/domain/__tests__/
4. Run cd packages/domain && npm test

Enhance UI on web

1. Check @repo/theme for existing tokens before adding new values
2. Check src/components/ui/ for existing primitives (Radix-based)
3. Use Tailwind utilities mapped to CSS vars (bg-background, text-foreground, etc.)
4. Test dark + light modes + all accent variants
5. Add testId props for automation

Add a mobile screen

1. Create src/screens/[name]/[Name]Screen.tsx
2. Add components/ subfolder for screen-local components
3. Register route in src/navigation/AppNavigator.tsx
4. Type the route in src/navigation/routes.ts
5. Use StyleSheet.create() with scale utils from constants.ts

13. Hard Rules (Never Violate)

1. Never commit .env files
2. Never use raw hex/rgb in Tailwind or StyleSheet — use theme tokens
3. Never import React/Expo/Next.js in packages/domain
4. Never skip requireAuth on user-facing Convex mutations
5. Never hardcode API URLs or keys — use @repo/config env vars
6. Never use any without a comment explaining why
7. Never write business logic (SM-2, scoring, streak) outside @repo/domain
8. Never block on Payload→Convex sync errors (fire-and-forget)
9. Never use Redux or Zustand — Convex + local state only
10. Always run lint + typecheck + test before marking a feature complete