trackgo-fe/.agents/skills/project-guidelines-example/SKILL.md

---
name: project-guidelines-example
description: Frontend monorepo guidelines for this pnpm + Turborepo React/Vite/Electron workspace. Use when scaffolding features, reviewing structure, or aligning code with this repo's conventions.
---

# Project Guidelines

Project skill for this frontend monorepo. Architecture, file layout, patterns, testing, and scripts as they exist in the repo today.

## When to Use

Reference this skill when working on this project. It contains:

- Architecture overview
- File structure
- Code patterns
- Testing requirements
- Related skills

---

## Architecture Overview

**Stack:**

- **Apps**: React 19 + Vite (`apps/web`, `apps/showcase`, `apps/landing`) + Electron (`apps/desktop`) + VitePress (`apps/docs-dev`)
- **Packages**: `@repo/ui` (Mantine), `@repo/core-api`, `@repo/core-storage`, `@repo/core-i18n`, `@repo/core-events`, `@repo/utils`, `@repo/brand`, `packages/configs`
- **Testing**: Vitest; Playwright E2E in `apps/web/e2e/`; Testing Library in `packages/ui` and `packages/core-events`
- **Package manager**: pnpm 8.15.6 + Turbo

**Where to work:** product in `apps/web`; copy UI/API usage from `apps/showcase`; concepts from `apps/docs-dev`. Do not invent a parallel UI kit.

---

## File Structure

```
.
├── apps/
│   ├── web/                 # Product app
│   ├── showcase/            # Living cookbook for @repo/*
│   ├── docs-dev/            # VitePress
│   ├── desktop/             # Electron wrapper of apps/web
│   └── landing/             # Marketing SPA
├── packages/
│   ├── ui/                  # @repo/ui — components, form, foundations
│   ├── core-api/            # HTTP client + remote data services
│   ├── core-storage/
│   ├── core-i18n/
│   ├── core-events/
│   ├── utils/
│   ├── brand/
│   └── configs/
└── package.json             # Root scripts
```

### Web module (copy `example/full-page`)

```
apps/web/src/apps/main/modules/<group>/<feature>/
  data/                      # *RemoteDataServices
  domain/
    constants/               # ModuleConfigEntity
    entities/
    factories/               # apiClient + service + transformer
    transformers/
    validators/              # Zod factories
  presentation/
    factory/                 # registerModuleNamespace + EnterpriseModuleProvider + routes
    pages/                   # index | form | detail
    components/
    store/                   # optional zustand
    languages/{en,id}/
```

Auth lives under `src/apps/auth/`. Shared-across-modules code lives in `src/core/`.

---

## Code Patterns

### Module config + factory

```typescript
import { ModuleConfigEntity } from '@repo/ui/foundations';

export const fullPageModuleConfig: ModuleConfigEntity = {
  moduleKey: 'EXAMPLE_FULL_PAGE',
  translationNamespace: 'EXAMPLE_FULL_PAGE',
  apiUrl: '/full-page',
  webUrl: '/app/example/full-page',
  moduleCategory: 'FULL_PAGE',
  moduleType: 'MASTER_DATA',
};
```

```tsx
import { EnterpriseModuleProvider } from '@repo/ui/foundations';
import { registerModuleNamespace } from '@repo/core-i18n';
import { apiClient } from '../../../../../../../core/lib/api-client';

registerModuleNamespace(fullPageModuleConfig.translationNamespace, { id, en });
```

### Validators (Zod)

```typescript
import { z } from 'zod';
import { compose, required, rangeLength } from '@repo/ui/validators';

export const createFullPageSchema = (t: (key: string) => string) =>
  z.object({
    code: compose(z.string(), required(t('common:fields.code'))),
    name: compose(z.string(), required(t('common:fields.name')), rangeLength(3, 50, t('common:fields.name'))),
  });
```

### Forms and HTTP

- Form fields: `FieldTextInput` and other `Field*` from `@repo/ui/form`
- HTTP: `apiClient` from `src/core/lib/api-client` (built with `createHttpClient`). Never raw axios.
- Env: `ENV` from `src/core/environment`. Files only in `apps/web/.env*`.

---

## Testing Requirements

```bash
pnpm test
pnpm --filter web test
pnpm test:e2e:web
pnpm --filter @repo/ui test
pnpm typecheck:web
pnpm check:all
```

- Unit tests colocated as `*.test.ts(x)`
- Component tests with Testing Library in packages that already have it
- App journeys: Playwright in `apps/web/e2e/` (login is the first sample)
- Minimum 80% coverage; TDD (red → green → refactor)

---

## Scripts

```bash
pnpm dev:web
pnpm dev:showcase
pnpm dev:docs-dev
pnpm lint
pnpm typecheck:web
pnpm test
pnpm test:e2e:web
pnpm check:all
```

### Env (apps/web)

See `apps/web/.env.example`. Typical `VITE_*` keys: `VITE_APP_ENV`, `VITE_API_BASE_URL`, telemetry URLs. All `VITE_*` values are public to the client.

---

## Critical Rules

1. **No emojis** in code, comments, or documentation
2. **Immutability** — never mutate objects or arrays
3. **TDD** — tests before implementation
4. **80% coverage** minimum
5. **Many small files** — 200–400 lines typical, 800 max
6. **No console.log** in production code
7. **No raw Mantine/axios** — use `@repo/ui` and `apiClient`
8. **Input validation** with Zod + `@repo/ui/validators`
9. Copy `example/full-page`; do not invent a third layout

---

## Related Skills

- `.agents/skills/coding-standards/` — TypeScript/React practices
- `.agents/skills/form-layout/` — form layout
- `.agents/skills/detail-layout/` — detail page layout
- `.agents/skills/index-layout/` — index / list table layout
- `.agents/skills/tdd-workflow/` — TDD
- `.agents/skills/security-review/` — frontend/Electron security