Frontend Layer

Frontend Layer

Location: frontend/ (separate from Python backend)

Stack: React 19 · TypeScript · Vite · MUI

---

Terminal Commands

Use Push-Location/Pop-Location to run npm commands without changing the working directory:

Push-Location frontend; npm run lint; Pop-Location
Push-Location frontend; npm run build; Pop-Location

Never use cd frontend - it changes the terminal's working directory permanently.

---

Required Verification

After ANY frontend change, run:

Push-Location frontend; npm run lint; npm run build; Pop-Location

The build script runs tsc -b (type-check) then Vite build.

Do not complete frontend work until both pass.

---

Structure

frontend/​src/
├── main.tsx           # Entry point
├── App.tsx            # Root component
├── theme.ts           # MUI theme
├── components/        # Shared UI (layout, widgets)
├── features/          # Feature modules (auth, library, analytics, ...)
├── hooks/             # Custom React hooks
├── router/            # Route definitions
└── shared/            # API client, types, utilities
    ├── api.ts         # Typed backend client
    ├── types.ts       # TypeScript interfaces
    └── auth.ts        # Session utilities

---

Rules

TypeScript

• Strict mode - no any
• Explicit return types on exports
• Interface for object shapes, type for unions

React

• Functional components only
• Feature-based folders (not type-based)
• Hooks for state management

MUI

• Use MUI components, not raw HTML
• Use sx prop, not inline styles
• Reference theme tokens, don't hardcode colors

---

API Client

All backend calls use shared/​api.ts:

import { api } from '../​shared/​api';

const stats = await api.library.getStats();

Adding endpoints:

1. Add interface to shared/​types.ts
2. Add method to shared/​api.ts

---

Completion Checklist

1. ☐ npm run lint passes
2. ☐ npm run build passes
3. ☐ No console.log in committed code
4. ☐ No hardcoded URLs

---

Layer Scripts

This skill includes validation scripts in .github/​skills/​layer-frontend/​scripts/:

lint.py

Runs ESLint and TypeScript type checking:

python .github/​skills/​layer-frontend/​scripts/​lint.py

Runs npm run lint from the frontend directory.

build.py

Runs the full build (typecheck + Vite):

python .github/​skills/​layer-frontend/​scripts/​build.py

Runs npm run build from the frontend directory.