Researched: 2026-03-24 Domain: Full-stack foundation (FastAPI auth, React design system, i18n, pluggable AI adapters) Confidence: HIGH

Phase 1 establishes the complete application scaffold: backend JWT authentication with User/Admin roles, frontend React SPA with login page and two responsive layout shells (user top-nav, admin sidebar), a shared component library adapted from Figma Make generated code (shadcn/ui + Radix primitives), react-i18next for zh-CN/en-US internationalization, and an extended pluggable adapter pattern for all AI services (LLM, STT, TTS, Avatar).

The project has a strong starting position. The backend already has: async SQLAlchemy with session management, FastAPI with lifespan/CORS/exception handling, a working adapter pattern (BaseCoachingAdapter + AdapterRegistry + MockCoachingAdapter), pydantic-settings configuration, test infrastructure with in-memory SQLite. The frontend has: Vite 6 + Tailwind CSS v4 configured, Axios client with JWT interceptor, cn() utility, @/ path alias. What is missing: all ORM models, schemas, API routers, React entry point (index.html, main.tsx, App.tsx), any pages/components, routing, i18n, and the React app shell itself.

The Figma Make exports in figma-make/ provide a complete set of shadcn/ui components and layout shells that need adaptation (import paths, design token alignment, i18n integration) rather than writing from scratch. The adaptation work is the largest frontend effort; the backend auth is standard FastAPI/JWT pattern.

Primary recommendation: Adapt Figma Make components into frontend/src/components/ui/, build backend auth (User model + JWT endpoints + role middleware), wire up React Router with auth guards, integrate react-i18next from day 1, and extend the existing adapter registry pattern to cover STT/TTS/Avatar service categories.

<user_constraints>

• D-01: Adapt Figma Make generated code into the project -- extract components from figma-make/Design System for SaaS/ and figma-make/Design Login and Layout Shell/, adapt to match project conventions (path aliases, Tailwind v4 design tokens, i18n). Keep figma-make/ as reference, not as runtime code.
• D-02: Component library is shadcn/ui-based (Radix primitives) -- already present in Figma Make exports. Adapt rather than rebuild.
• D-03: Components organized as components/ui/ (generic primitives: Button, Card, Input, Tabs, etc.) + components/coach/, components/admin/ (domain-specific composites). Matches existing directory structure.
• D-04: Figma Make design tokens take priority over existing frontend/src/styles/index.css values -- Figma design is the source of truth. Primary Blue #1E40AF, Inter + Noto Sans SC fonts, 8px radius cards.
• D-05: Two layout shells -- User gets top-nav layout, Admin gets sidebar layout. Same shared components in both, different arrangements. Adapted from Figma Make Layout Shell code.
• D-06: Phase 1 delivers responsive web covering desktop, tablet, mobile, and Teams Tab (iframe). WeChat Mini Program requires a separate frontend -- deferred to future phase. Backend REST API contracts serve all clients.
• D-07: Frontend and backend both fully modular -- reusable components, domain-specific hooks, service layer separation.

• Auth flow: JWT in localStorage (Axios client already configured), python-jose + passlib for backend, simple username/password login, role-based route protection via React Router guards
• App shell: Adapt directly from Figma Make Layout Shell -- user top-nav (64px, logo + nav links + language switcher + avatar) and admin sidebar (240px, dark blue #1E293B, collapsible)
• i18n: react-i18next with namespace-based translation files (common.json, auth.json, etc.), persist language preference in localStorage, zh-CN + en-US from day 1
• Feature toggles: Config-driven via pydantic-settings backend + Vite env vars frontend, mock providers work without Azure credentials
• Responsive breakpoints: Mobile-first, hamburger menu on mobile for both layouts

• WeChat Mini Program -- requires separate frontend, deferred to post-v1
• Teams Bot integration -- post-MVP
• Per-region theming/branding -- not needed for v1 </user_constraints>

<phase_requirements>

Key directives that constrain all implementation:

• Async everywhere in backend: async def, await, AsyncSession -- no sync DB calls
• Pydantic v2 schemas with model_config = ConfigDict(from_attributes=True)
• Route ordering: Static paths before parameterized paths
• Create returns 201, Delete returns 204
• Service layer holds business logic; routers only handle HTTP
• No raw SQL -- SQLAlchemy ORM or Alembic migrations only
• TypeScript strict mode: strict: true, no any, no unused variables, noUncheckedIndexedAccess: true
• TanStack Query hooks per domain, no inline useQuery
• @/ path alias for all imports from src/
• cn() utility for conditional class composition
• No Redux -- TanStack Query for server state, lightweight store for auth
• Conventional commits: feat:, fix:, docs:, test:
• NEVER modify DB schema without Alembic migration
• All routes under /api/v1/ prefix
• Structured error responses: {"code": "ERROR_CODE", "message": "...", "details": {...}}
• Pre-commit checks: ruff check ., ruff format --check ., pytest -v (backend); npx tsc -b, npm run build (frontend)
• Ruff: line-length 100, double quotes, target py311
• Docker: multi-stage builds, python:3.11-slim backend, node:20-slim build + nginx:alpine serve frontend

Installation (frontend new deps):

cd frontend
npm install react-i18next i18next i18next-browser-languagedetector i18next-http-backend
npm install @radix-ui/react-slot @radix-ui/react-dropdown-menu @radix-ui/react-dialog @radix-ui/react-avatar @radix-ui/react-label @radix-ui/react-separator @radix-ui/react-tooltip @radix-ui/react-navigation-menu @radix-ui/react-checkbox @radix-ui/react-select @radix-ui/react-switch
npm install class-variance-authority sonner vaul

Note: Only install Radix primitives actually used by Phase 1 components. The full Figma Make package.json lists many more (accordion, tabs, popover, etc.) -- add those in later phases when their components are needed.

backend/
  app/
    api/
      __init__.py
      auth.py               # POST /login, POST /refresh, GET /me
    models/
      __init__.py
      base.py               # (exists) Base + TimestampMixin
      user.py               # NEW: User ORM model
    schemas/
      __init__.py
      auth.py               # NEW: LoginRequest, TokenResponse, UserResponse
      user.py               # NEW: UserCreate, UserUpdate, UserRead
    services/
      auth.py               # NEW: authenticate_user, create_token, hash_password
      agents/
        base.py             # (exists) BaseCoachingAdapter
        registry.py          # (exists) AdapterRegistry
        adapters/
          mock.py            # (exists) MockCoachingAdapter
        stt/
          base.py            # NEW: BaseSTTAdapter (speech-to-text)
          mock.py            # NEW: MockSTTAdapter
        tts/
          base.py            # NEW: BaseTTSAdapter (text-to-speech)
          mock.py            # NEW: MockTTSAdapter
        avatar/
          base.py            # NEW: BaseAvatarAdapter
          mock.py            # NEW: MockAvatarAdapter
    dependencies.py          # (extend) get_current_user, require_role("admin")
    config.py                # (extend) feature flags, voice mode, region config

frontend/
  public/
    locales/
      en-US/
        common.json          # Shared UI text
        auth.json            # Login page text
        nav.json             # Navigation labels
      zh-CN/
        common.json
        auth.json
        nav.json
  src/
    components/
      ui/                    # Adapted from figma-make/Design System for SaaS/
        button.tsx
        card.tsx
        input.tsx
        label.tsx
        badge.tsx
        separator.tsx
        dropdown-menu.tsx
        avatar.tsx
        checkbox.tsx
        select.tsx
        switch.tsx
        tooltip.tsx
        skeleton.tsx
        sheet.tsx
        dialog.tsx
        form.tsx
        sonner.tsx           # Toast
        index.ts             # Barrel export
      shared/
        language-switcher.tsx
        loading-state.tsx
        empty-state.tsx
      layouts/
        user-layout.tsx      # Adapted from figma-make UserLayout
        admin-layout.tsx     # Adapted from figma-make AdminLayout
        auth-layout.tsx      # Login page wrapper
    pages/
      login.tsx              # Adapted from figma-make Login
      user/
        dashboard.tsx        # Placeholder
      admin/
        dashboard.tsx        # Placeholder
      not-found.tsx
    hooks/
      use-auth.ts            # TanStack Query: login mutation, refresh, me query
    stores/
      auth-store.ts          # JWT token + user info in localStorage
    contexts/
      auth-context.tsx       # AuthProvider + useAuth hook
    types/
      auth.ts                # User, LoginRequest, TokenResponse types
      config.ts              # FeatureFlags, AppConfig types
    i18n/
      index.ts               # i18next init + config
      types.ts               # Type-safe namespace keys (optional)
    lib/
      utils.ts               # (exists) cn()
      config.ts              # Runtime feature flag reader
    router/
      index.tsx              # Route definitions with auth guards
      auth-guard.tsx         # ProtectedRoute, AdminRoute components
    App.tsx                  # Root component: providers (Query, i18n, Auth, Router)
    main.tsx                 # ReactDOM.createRoot entry point
  index.html                 # Vite HTML entry

What: Standard FastAPI JWT auth with role-based access control When to use: All authenticated endpoints

Backend flow:

# backend/app/services/auth.py
from datetime import datetime, timedelta, timezone
from passlib.context import CryptContext
from jose import JWTError, jwt
from app.config import get_settings

pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
settings = get_settings()

def verify_password(plain_password: str, hashed_password: str) -> bool:
    return pwd_context.verify(plain_password, hashed_password)

def get_password_hash(password: str) -> str:
    return pwd_context.hash(password)

def create_access_token(data: dict, expires_delta: timedelta | None = None) -> str:
    to_encode = data.copy()
    expire = datetime.now(timezone.utc) + (expires_delta or timedelta(minutes=settings.access_token_expire_minutes))
    to_encode.update({"exp": expire})
    return jwt.encode(to_encode, settings.secret_key, algorithm=settings.algorithm)

Backend dependency:

# backend/app/dependencies.py
from fastapi import Depends
from fastapi.security import OAuth2PasswordBearer
from jose import JWTError, jwt
from sqlalchemy.ext.asyncio import AsyncSession

oauth2_scheme = OAuth2PasswordBearer(tokenUrl=f"{settings.api_prefix}/auth/login")

async def get_current_user(
    token: str = Depends(oauth2_scheme),
    db: AsyncSession = Depends(get_db),
) -> User:
    # Decode JWT, query user from DB, raise 401 if invalid
    ...

def require_role(role: str):
    async def role_checker(user: User = Depends(get_current_user)) -> User:
        if user.role != role:
            raise AppException(403, "FORBIDDEN", "Insufficient permissions")
        return user
    return role_checker

What: Role-based route protection using React Router layout routes When to use: All protected pages

// router/auth-guard.tsx
import { Navigate, Outlet } from "react-router-dom";
import { useAuthStore } from "@/stores/auth-store";

export function ProtectedRoute() {
  const { token, user } = useAuthStore();
  if (!token) return <Navigate to="/login" replace />;
  return <Outlet />;
}

export function AdminRoute() {
  const { user } = useAuthStore();
  if (user?.role !== "admin") return <Navigate to="/user/dashboard" replace />;
  return <Outlet />;
}

What: react-i18next initialized with lazy-loaded namespace JSON files When to use: All UI text

// src/i18n/index.ts
import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import LanguageDetector from "i18next-browser-languagedetector";
import HttpBackend from "i18next-http-backend";

i18n
  .use(HttpBackend)
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    fallbackLng: "en-US",
    supportedLngs: ["en-US", "zh-CN"],
    defaultNS: "common",
    ns: ["common", "auth", "nav"],
    backend: {
      loadPath: "/locales/{{lng}}/{{ns}}.json",
    },
    detection: {
      order: ["localStorage", "navigator"],
      caches: ["localStorage"],
      lookupLocalStorage: "i18nextLng",
    },
    interpolation: {
      escapeValue: false, // React already escapes
    },
  });

export default i18n;

Usage in components:

import { useTranslation } from "react-i18next";

function LoginPage() {
  const { t } = useTranslation("auth");
  return <h1>{t("title")}</h1>; // Reads from auth.json
}

What: Extend existing BaseCoachingAdapter pattern to STT, TTS, Avatar service categories When to use: All AI service integrations

# backend/app/services/agents/stt/base.py
from abc import ABC, abstractmethod

class BaseSTTAdapter(ABC):
    """Abstract base for Speech-to-Text adapters."""
    name: str = ""

    @abstractmethod
    async def transcribe(self, audio_data: bytes, language: str = "zh-CN") -> str:
        """Transcribe audio to text."""
        ...

    @abstractmethod
    async def is_available(self) -> bool:
        ...

Each service category (STT, TTS, Avatar) follows the same Base + Registry + Mock pattern as the existing coaching adapter. The AdapterRegistry can be extended to a ServiceRegistry that manages multiple registries by category.

What: Config-driven feature availability using pydantic-settings + Vite env vars When to use: All optional features (Avatar, voice modes, etc.)

# backend/app/config.py (additions)
class Settings(BaseSettings):
    # ... existing fields ...

    # Feature toggles
    feature_avatar_enabled: bool = False
    feature_voice_enabled: bool = False
    feature_realtime_voice_enabled: bool = False

    # Voice mode: "text_only" | "stt_tts" | "realtime" | "voice_live"
    default_voice_mode: str = "text_only"

    # Region
    region: str = "global"  # "global" | "china" | "eu"

    # Azure Avatar (optional premium)
    azure_avatar_endpoint: str = ""
    azure_avatar_key: str = ""

Frontend reads config from backend API and/or Vite env vars:

// Environment-specific via Vite
const FEATURE_FLAGS = {
  avatarEnabled: import.meta.env.VITE_FEATURE_AVATAR === "true",
  voiceEnabled: import.meta.env.VITE_FEATURE_VOICE === "true",
};

What: Copy shadcn/ui components from figma-make/ to frontend/src/components/ui/, adapt imports When to use: All UI components in Phase 1

Adaptation checklist per component:

1. Copy .tsx file from figma-make/Design System for SaaS/src/app/components/ui/
2. Change import { cn } from "./utils" to import { cn } from "@/lib/utils"
3. Verify Tailwind v4 CSS variable names match project index.css (align with Figma Make theme.css)
4. Add i18n where component has user-visible text
5. Ensure TypeScript strict compliance (noUnusedLocals, noUnusedParameters)
6. Export from barrel index.ts

• Inline translations: Never hardcode Chinese/English strings in components. Always use t("key") from react-i18next.
• Sync database calls: All backend functions must be async def. Never use synchronous SQLAlchemy patterns.
• Direct role checks in components: Use AdminRoute/ProtectedRoute guards at the router level, not {user.role === "admin" && <Component />} in components.
• Hardcoded Azure endpoints: All service URLs, keys, and regions must come from Settings -- never inline strings.
• Custom cn() in UI components: Figma Make components have their own utils.ts with an identical cn(). Replace all imports to use the project's @/lib/utils.
• Installing all Radix packages at once: Only install Radix primitives needed by Phase 1 components. The Figma Make package.json lists 20+ Radix packages, but many are for later phases.

Key insight: Every UI primitive (dropdown, dialog, tooltip, checkbox) must come from Radix UI via the shadcn/ui wrappers. Building custom versions loses accessibility (focus trapping, keyboard nav, ARIA attributes) and wastes time when the Figma Make exports already provide these.

What goes wrong: Figma Make components import cn from "./utils" (relative path). Project convention uses "@/lib/utils". Why it happens: Figma Make generates self-contained apps with local utility files. How to avoid: When adapting each component, search-and-replace from "./utils" with from "@/lib/utils". Delete components/ui/utils.ts -- use only lib/utils.ts. Warning signs: TypeScript compilation errors about missing ./utils module.

What goes wrong: Figma Make's theme.css uses shadcn/ui naming (--background, --foreground, --primary, --card) while the existing project index.css uses --color-primary-500 etc. Both use @theme inline but with different variable names. Why it happens: Two design token systems were created independently. How to avoid: Replace the existing frontend/src/styles/index.css with the Figma Make theme.css as the foundation (per decision D-04), then layer in the medical-themed color values (primary blue #1E40AF, etc.) and font stacks (Inter + Noto Sans SC). The shadcn/ui semantic naming (--primary, --card, --muted) is required for all adapted components to work. Warning signs: Components render with wrong colors or no styling; Tailwind classes like bg-primary don't match expected blue.

What goes wrong: Components using useTranslation("auth") show raw keys (auth.title) instead of translated text. Why it happens: With i18next-http-backend, namespace JSON files load asynchronously. If the component renders before the namespace loads, it shows keys. How to avoid: Wrap the app with <Suspense fallback={<LoadingState />}> and configure i18next to work with React Suspense: react: { useSuspense: true }. Or preload critical namespaces in i18n init. Warning signs: Flash of translation keys on page load, especially on slow networks.

What goes wrong: GET /api/v1/users/me matches GET /api/v1/users/{id} instead. Why it happens: FastAPI matches routes in declaration order. If /{id} is declared before /me, "me" is treated as an id. How to avoid: Always declare static routes (/me, /refresh, /defaults) before parameterized routes (/{id}). This is documented in CLAUDE.md Gotcha #3. Warning signs: 404 or wrong handler executing for /me, /refresh endpoints.

What goes wrong: passlib with bcrypt>=4.1.0 raises AttributeError: module 'bcrypt' has no attribute '__about__'. Why it happens: passlib has not been updated to support bcrypt 4.1+. The internal version check code accesses bcrypt.__about__.__version__ which was removed. How to avoid: Pin bcrypt<4.1.0 in pyproject.toml, or use passlib[bcrypt] which typically manages this. If issues arise, use bcrypt==4.0.1 explicitly. Alternatively, use CryptContext(schemes=["bcrypt"], deprecated="auto") which handles this gracefully in current passlib releases. Warning signs: Import errors or AttributeError when hashing passwords.

What goes wrong: Alembic migration fails with OperationalError when trying to alter a column in SQLite. Why it happens: SQLite does not support ALTER COLUMN. CLAUDE.md Gotcha #1. How to avoid: Use Alembic batch operations for SQLite: with op.batch_alter_table('users') as batch_op: batch_op.alter_column(...). Configure Alembic env.py with render_as_batch=True for SQLite. Warning signs: Migration errors in development (SQLite); no issue in production (PostgreSQL).

What goes wrong: Login API calls from frontend fail silently with no error in network tab. Why it happens: CORS not configured for the frontend dev server port. CLAUDE.md Gotcha #6. How to avoid: Ensure cors_origins in Settings includes http://localhost:5173. The Vite dev proxy at /api should bypass CORS, but direct API calls need it. Already configured in config.py default value. Warning signs: Browser console shows CORS errors; API requests blocked.

What goes wrong: alembic revision --autogenerate generates empty migrations -- no table changes detected. Why it happens: Alembic env.py does not import ORM model modules, so Base.metadata has no tables registered. CLAUDE.md Gotcha #7. How to avoid: In alembic/env.py, import all model modules: from app.models.user import User. Or import the models package __init__.py that re-exports them all. Warning signs: Auto-generated migration has no op.create_table() calls despite new models.

# backend/app/models/user.py
from sqlalchemy import String
from sqlalchemy.orm import Mapped, mapped_column

from app.models.base import Base, TimestampMixin


class User(Base, TimestampMixin):
    __tablename__ = "users"

    username: Mapped[str] = mapped_column(String(100), unique=True, nullable=False, index=True)
    email: Mapped[str] = mapped_column(String(255), unique=True, nullable=False)
    hashed_password: Mapped[str] = mapped_column(String(255), nullable=False)
    full_name: Mapped[str] = mapped_column(String(255), default="")
    role: Mapped[str] = mapped_column(String(20), default="user")  # "user" or "admin"
    is_active: Mapped[bool] = mapped_column(default=True)
    preferred_language: Mapped[str] = mapped_column(String(10), default="zh-CN")

# backend/app/schemas/auth.py
from pydantic import BaseModel, ConfigDict

class LoginRequest(BaseModel):
    username: str
    password: str

class TokenResponse(BaseModel):
    access_token: str
    token_type: str = "bearer"

class UserResponse(BaseModel):
    model_config = ConfigDict(from_attributes=True)

    id: str
    username: str
    email: str
    full_name: str
    role: str
    is_active: bool
    preferred_language: str

# backend/app/api/auth.py
from fastapi import APIRouter, Depends
from sqlalchemy.ext.asyncio import AsyncSession

from app.dependencies import get_db
from app.schemas.auth import LoginRequest, TokenResponse, UserResponse
from app.services.auth import authenticate_user, create_access_token

router = APIRouter(prefix="/auth", tags=["auth"])

@router.post("/login", response_model=TokenResponse)
async def login(request: LoginRequest, db: AsyncSession = Depends(get_db)):
    user = await authenticate_user(db, request.username, request.password)
    token = create_access_token(data={"sub": user.id, "role": user.role})
    return TokenResponse(access_token=token)

@router.get("/me", response_model=UserResponse)
async def get_me(user = Depends(get_current_user)):
    return user

// src/stores/auth-store.ts
interface AuthState {
  token: string | null;
  user: User | null;
}

// Simple store using module-level state + subscription pattern
// Or use zustand if preferred -- but keep lightweight per CLAUDE.md
let state: AuthState = {
  token: localStorage.getItem("access_token"),
  user: null,
};

const listeners = new Set<() => void>();

export function useAuthStore() {
  // React 18 useSyncExternalStore pattern
  return useSyncExternalStore(subscribe, getSnapshot);
}

export function setAuth(token: string, user: User) {
  localStorage.setItem("access_token", token);
  state = { token, user };
  listeners.forEach((l) => l());
}

export function clearAuth() {
  localStorage.removeItem("access_token");
  state = { token: null, user: null };
  listeners.forEach((l) => l());
}

// public/locales/en-US/auth.json
{
  "title": "AI Coach",
  "email": "Email",
  "password": "Password",
  "rememberMe": "Remember me",
  "signIn": "Sign In",
  "signingIn": "Signing in...",
  "loginFailed": "Invalid username or password",
  "copyright": "2026 AI Coach Platform"
}

// public/locales/zh-CN/auth.json
{
  "title": "AI 教练",
  "email": "邮箱",
  "password": "密码",
  "rememberMe": "记住我",
  "signIn": "登录",
  "signingIn": "登录中...",
  "loginFailed": "用户名或密码错误",
  "copyright": "2026 AI 教练平台"
}

// src/components/ui/button.tsx
// Adapted from figma-make/Design System for SaaS/src/app/components/ui/button.tsx
// Changes: import path for cn(), removed data-slot (optional)
import * as React from "react";
import { Slot } from "@radix-ui/react-slot";
import { cva, type VariantProps } from "class-variance-authority";
import { cn } from "@/lib/utils";  // CHANGED: was "./utils"

const buttonVariants = cva(
  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        destructive: "bg-destructive text-white hover:bg-destructive/90",
        outline: "border bg-background text-foreground hover:bg-accent hover:text-accent-foreground",
        secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
        ghost: "hover:bg-accent hover:text-accent-foreground",
        link: "text-primary underline-offset-4 hover:underline",
      },
      size: {
        default: "h-9 px-4 py-2 has-[>svg]:px-3",
        sm: "h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5",
        lg: "h-10 rounded-md px-6 has-[>svg]:px-4",
        icon: "size-9 rounded-md",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  },
);

// ... rest identical to Figma Make version

Deprecated/outdated:

• @app.on_event("startup") / @app.on_event("shutdown"): Replaced by lifespan asynccontextmanager in FastAPI (already used in project)
• Optional[X]: Use X | None syntax (Python 3.10+, project targets 3.11)
• tailwind.config.js: Not used in Tailwind CSS v4; all config via CSS @theme inline

1. Alembic env.py does not exist yet

   • What we know: The backend/alembic/ directory exists with a versions/ subdirectory but no env.py, alembic.ini, or script template
   • What's unclear: Whether Alembic was initialized and files were deleted, or it was never initialized
   • Recommendation: Run alembic init alembic to generate the configuration, then customize env.py to use async engine and import all models. Also create alembic.ini in the backend root.

2. Frontend entry point files missing

   • What we know: index.html, src/main.tsx, src/App.tsx do not exist. The frontend has no runnable app yet.
   • What's unclear: Whether there was a deliberate decision to defer these or they were simply never created
   • Recommendation: Create these as part of the first task. They are prerequisite to all other frontend work.

3. Auth store implementation choice

   • What we know: CLAUDE.md says "lightweight store for auth, no Redux". Options: React Context, zustand, useSyncExternalStore, or simple module state.
   • What's unclear: Whether to add zustand as a dependency or use a zero-dependency approach
   • Recommendation: Use React Context + useState for the auth provider since it is the simplest zero-dependency approach. If more stores are needed in later phases, add zustand then.

4. Seed data for development

   • What we know: backend/scripts/seed_data.py is referenced in CLAUDE.md Quick Start but does not exist. Phase 1 needs at least one admin and one user account for development/testing.
   • What's unclear: What the seed data format should look like
   • Recommendation: Create seed_data.py that inserts a default admin (admin/admin123) and user (user/user123) with hashed passwords.

Missing dependencies with no fallback: None -- all required tools are available.

Missing dependencies with fallback: Docker is not checked but is not required for local development (SQLite is the dev database).

• Project codebase: backend/app/config.py, backend/app/main.py, backend/app/services/agents/ -- existing patterns verified by direct code reading
• Figma Make exports: figma-make/Design System for SaaS/, figma-make/Design Login and Layout Shell/ -- component structure and dependencies verified
• figma-make/Design System for SaaS/package.json -- dependency versions verified against npm registry
• CLAUDE.md -- all project constraints and coding conventions
• docs/figma-prompts/00-design-system.md, docs/figma-prompts/01-login-and-layout.md -- design specifications

• npm registry: Package versions verified via npm view for react-i18next (16.6.2), i18next (25.10.5), i18next-browser-languagedetector (8.2.1), i18next-http-backend (3.0.2), @radix-ui/react-slot (1.2.4), class-variance-authority (0.7.1), react-router-dom (7.13.2), sonner (2.0.7), vaul (1.1.2), tailwind-merge (3.5.0)
• pip installed packages: Verified python-jose (3.3.0), passlib (1.7.4), FastAPI (0.115.0), pydantic-settings (2.5.2)

• bcrypt version incompatibility with passlib: Based on training data knowledge of a known issue in 2024. Should verify current state of passlib compatibility before implementation. If issues arise, pin bcrypt version.
• Web search was unavailable during research. All library API patterns are based on training knowledge and should be verified against official documentation during implementation.

Confidence breakdown:

• Standard stack: HIGH -- All libraries already in project dependencies or verified via npm/pip registries. No speculative recommendations.
• Architecture: HIGH -- Patterns extend existing codebase patterns (adapter, DI, config). Figma Make components inspected directly.
• Pitfalls: MEDIUM -- Some pitfalls from training data (bcrypt compat), others verified from CLAUDE.md gotchas. Web search unavailable for latest community reports.
• Code examples: MEDIUM -- Based on standard library patterns and existing code. Should be validated against latest API docs during implementation.

Research date: 2026-03-24 Valid until: 2026-04-24 (30 days -- stable ecosystem, no fast-moving dependencies)

Visual and interaction contract for the foundation phase: login page, responsive app shell (user + admin layouts), shared component library, and i18n. Generated by gsd-ui-researcher, verified by gsd-ui-checker.

Source: CONTEXT.md D-01, D-02; RESEARCH.md Standard Stack; Figma Make fonts.css

Note: No components.json exists because the project adapts pre-generated Figma Make shadcn/ui components into frontend/src/components/ui/ rather than using npx shadcn add. All Radix primitives are installed as direct npm dependencies. The registry safety gate for npx shadcn preset automation does not apply.

Declared values (must be multiples of 4):

Exceptions:

• Top-nav bar height: 64px (matches 3xl token) -- source: Figma prompt A2
• Admin top-bar height: 56px (7 * 8px, consistent with 8-point scale) -- source: Figma prompt A3
• Admin sidebar width: 240px (30 * 8px) -- source: CONTEXT.md Claude's Discretion
• Login card width: 480px (60 * 8px) -- source: Figma prompt A1
• Mobile touch target minimum: 44px (WCAG 2.5.5 conformance)

Source: Figma prompts 00/01; CONTEXT.md Claude's Discretion (sidebar 240px, top-nav 64px)

Font stack: 'Inter', 'Noto Sans SC', sans-serif

The Figma Make theme.css uses Tailwind's default text size scale (--text-base, --text-lg, --text-xl, --text-2xl) and declares only two font weights: 400 and 500. All heading levels, labels, and buttons use weight 500. Body text and inputs use weight 400. Line height is uniformly 1.5 across all roles.

Sizes declared (4 total): 16px, 18px, 20px (h2), 24px (h1) Weights declared (2 total): 400 (normal), 500 (medium)

Source: Figma Make theme.css lines 166-206; Figma prompt 00 (Inter + Noto Sans SC)

The accent color #1E40AF (primary blue) is reserved ONLY for:

1. Primary CTA buttons ("Sign In", main action per page)
2. Active navigation indicator (underline or background highlight)
3. Text links that navigate (not all interactive elements)
4. Focus ring on form inputs (via --ring token)
5. Active sidebar menu item background (admin layout)
6. Logo mark color

It is NOT used for: card borders, section backgrounds, badges (use --secondary or --muted instead), or general hover states (use --accent #E9EBEF instead).

Source: Figma Make theme.css; CONTEXT.md D-04 (Figma tokens are source of truth); Figma prompt 00 (color scheme)

Note: Figma prompt 00 specifies "8px cards, 6px buttons, 4px inputs". The Figma Make theme.css calculates from a 10px base. The effective values are: cards use --radius-md (8px), buttons use --radius-sm (6px). Input radius should use --radius-sm (6px) to match the Figma spec closely, though the prompt says 4px -- defer to the generated code which uses 6px.

Source: Figma Make theme.css lines 134-137; Figma prompt 00

Source: Figma prompt 00 ("shadows: subtle 0 1px 3px rgba(0,0,0,0.1)")

Source: Figma prompts A1/A2/A3; CONTEXT.md D-05, Claude's Discretion (responsive breakpoints)

All copy is delivered via react-i18next translation keys. The table below defines the canonical English copy; Chinese translations live in public/locales/zh-CN/ namespace files.

There are no destructive actions in Phase 1. The login page and layout shell do not include delete or irreversible operations. Logout is not destructive (session can be re-established by logging in again).

Source: RESEARCH.md code examples (i18n translation files); Figma prompts A1/A2/A3 (layout labels)

These components are copied from figma-make/Design System for SaaS/src/app/components/ui/ and adapted per RESEARCH.md Pattern 6 (import path fix, TypeScript strict compliance, barrel export).

Note: Because components are adapted from local Figma Make exports (not fetched from a remote registry at install time), the registry vetting gate for third-party code does not apply. The Figma Make source code was generated by Figma and lives in the project repository under figma-make/.

The Figma Make theme.css includes a complete .dark class variant. Phase 1 does NOT implement dark mode toggle UI, but the design tokens are defined for both modes. Dark mode support can be added in a future phase by adding a theme toggle component that applies the .dark class to the document root.

Phase 1 scope: Light mode only. Dark mode tokens are preserved in the theme CSS but not exposed to the user.

• Dimension 1 Copywriting: PASS
• Dimension 2 Visuals: PASS
• Dimension 3 Color: PASS
• Dimension 4 Typography: PASS
• Dimension 5 Spacing: PASS
• Dimension 6 Registry Safety: PASS

Approval: pending

Phase Goal: A running application with login, responsive layout shell, shared component library, i18n framework, and pluggable architecture for all AI services -- the scaffold everything else builds on Verified: 2026-03-24T14:45:00Z Status: passed Re-verification: No -- initial verification

Score: 5/5 truths verified

All 17 UI components exist in frontend/src/components/ui/: button, card, input, label, checkbox, avatar, dropdown-menu, select, separator, tooltip, sheet, dialog, switch, skeleton, badge, sonner, form.

All 16 requirement IDs from the phase are accounted for and satisfied.

Note: The 5 ruff lint errors are all in files that pre-date Phase 1 execution (created in initial project setup commit 2ed79ab). They are not regressions introduced by Phase 1. The Plan 05 SUMMARY explicitly documents this: "Pre-existing ruff lint warnings in files from prior plans -- out of scope."

Test: Start backend (cd backend && python scripts/seed_data.py && uvicorn app.main:app --reload --port 8000) and frontend (cd frontend && npm run dev). Navigate to http://localhost:5173. Expected: Login page shows centered card on gradient background with email/password fields, show/hide toggle, remember me checkbox, Sign In button, and copyright footer. Language switcher in bottom-right corner. Why human: Visual appearance, gradient rendering, and component spacing cannot be verified programmatically.

Test: Login with admin/admin123 credentials. Expected: Redirected to admin dashboard. Left sidebar with dark blue (#1E293B) background, 8 nav items with icons, AI Coach Admin header, collapse toggle. Clicking collapse narrows sidebar to icon-only (64px) with tooltips. Why human: Sidebar collapse animation, dark theme rendering, tooltip positioning require visual inspection.

Test: Log out, login with user1/user123 credentials. Expected: Redirected to user dashboard. Top navigation bar at 64px height with logo, nav links (Dashboard, Training, History, Reports), language switcher, bell icon, and avatar dropdown with sign out option. Why human: Navigation bar alignment, active link highlighting, dropdown menu behavior require visual inspection.

Test: Resize browser to mobile width (<640px). Expected: Hamburger menu replaces nav links. Clicking hamburger opens Sheet drawer with nav items. Why human: Responsive breakpoints and Sheet overlay behavior require real viewport testing.

Test: Click language switcher globe icon. Select Chinese. Expected: All visible text changes to Chinese (login labels, nav items, button text). Refreshing the page maintains the language choice. Why human: Complete text coverage across all visible components requires visual confirmation.

No gaps found. All 5 success criteria from ROADMAP.md are verified through code inspection and automated tests. All 16 requirement IDs are accounted for with implementation evidence. Backend tests (51/51) pass, frontend TypeScript compiles clean under strict mode, and Vite production build succeeds. The 5 ruff lint warnings are pre-existing in files from the initial project skeleton (before Phase 1 plans) and do not affect Phase 1 deliverables.

The dashboard placeholder pages are intentional (documented as known stubs in Plan 04 SUMMARY) -- they serve as navigation targets for the layout shell and will be populated with real content in Phase 2.

All 5 SUMMARY.md files exist and are complete:

• 01-01-SUMMARY.md (JWT auth, 10min, 16 files)
• 01-02-SUMMARY.md (Design tokens + UI components, 12min, 22 files)
• 01-03-SUMMARY.md (AI adapters + config, 7min, 15 files)
• 01-04-SUMMARY.md (Frontend shell, 8min, 29 files)
• 01-05-SUMMARY.md (Integration wiring, 6min, 6 files)

Verified: 2026-03-24T14:45:00Z Verifier: Claude (gsd-verifier)