Imported from beratersari/swyngora (frontend/AGENTS.md). Install upstream with npx skills add beratersari/swyngora --skill frontend. Copyright stays with the author.

AGENTS.md — frontend/

Package conventions for the product web UI. Closest AGENTS.md wins under this tree; user chat overrides docs. Root AGENTS.md still applies for Git Flow, SemVer, and monorepo rules.

1. Role

React SPA that talks to the Go backend via OpenAPI-described HTTP. Not simple-frontend/.

2. Stack (mandatory)

Decision record: project-management/decisions/001-antd-and-lightweight-charts.md
Design system: docs/design/frontend-design-system.md

3. Folder map (Option A — no features/)

Do not use src/features/ for product UI. Domain widgets live under organisms; screens under pages. Revisit feature folders only when multiple product areas need isolation (e.g. markets + watchlist + paper + AI).

UI strings: use useTranslation / t('namespace:key') — catalogs in libs/i18n/locales/. Exchange ids and symbols stay untranslated.

Full design: docs/design/frontend-system-design.md.
Local tasks: project-management/.

File naming (searchable colocation)

Every component module uses the component name as a prefix so search/filter finds related files easily:

components/atoms/Text/
├── Text.tsx              # component
├── Text.types.ts         # props / local types
├── Text.styles.ts        # styled-components
├── Text.constants.ts     # local constants (not bare constants.ts)
├── Text.helpers.ts       # pure helpers (not bare helpers.ts)
├── Text.test.tsx         # tests
└── index.ts              # public barrel

Do not use bare constants.ts / helpers.ts / styles.ts inside component folders — always prefix with the component name.

App-level config may use src/config/constants.ts (not a component).

4. Ant Design rules

1. App-wide theme via ConfigProvider in app/providers.tsx (INIT-8).
2. Prefer Atomic wrappers (components/atoms/Button, etc.) over raw antd deep in the tree — organisms may use antd Table/Form when wrappers do not exist yet; promote wrappers as patterns stabilize.
3. Use Ant Design Table, Tabs, Form, Select, Input, Layout, Typography, Tag, Pagination, Spin, Alert for markets UI.
4. Do not mix a second full UI kit (MUI, Chakra, etc.) without a decision doc.

5. Chart rules (Lightweight Charts)

1. Dependency: lightweight-charts (INIT-9).
2. Mount charts in a dedicated molecule/organism (e.g. candle chart host); do not put chart lifecycle in atoms that only render icons/text.
3. Map API candle strings → chart numbers in libs/utils.
4. Primary use: OHLCV from GET /api/v1/market/candles on detail views (later epic). Markets list phase uses tables, not charts.
5. Do not add ECharts/Recharts/Chart.js as a second default without a new decision.

6. Hard rules

1. API layer only under libs/api — never under components or a features/*/api tree.
2. Shared hooks under libs/hooks.
3. Shared pure code under libs/utils.
4. Do not call fetch/axios / RTK from atoms, molecules, or organisms — pages only.
5. Do not hand-edit libs/api/generated/.
6. Do not hand-maintain long-term API DTOs that duplicate OpenAPI.
7. libs must not import pages or organisms.
8. No upward Atomic imports (atoms must not import organisms/pages).
9. No src/features/ unless the team explicitly revisits Option B (feature-owned pages).
10. User-visible work lands with tests and docs.
11. Keep this file and README.md accurate after structural/stack changes.

7. Preferred imports

import { useListSpotMarketsQuery } from '@/libs/api';
import { useDocumentVisible } from '@/libs/hooks';
import { formatPrice } from '@/libs/utils';
import { Button } from '@/components/atoms/Button';
import { MarketsTable } from '@/components/organisms/MarketsTable';

8. First epics

Do not implement Epic 2 UI before Epic 1 acceptance criteria pass.

9. Local run (post-init)

cd backend && go run ./cmd/server
cd frontend && npm install && npm run dev

10. Codegen

npm run codegen:api
# output: src/libs/api/generated/

11. Format / lint / test

npm run format         # Prettier write
npm run format:check   # CI check
npm run lint           # ESLint (+ eslint-config-prettier)
npm test               # Vitest
npm run test:coverage  # Vitest + @vitest/coverage-v8 (line + branch)

Config: .prettierrc.json · ignore: .prettierignore
Do not format src/libs/api/generated/.

Env (optional): VITE_API_BASE_URL, VITE_CLIENT_ID (watchlist X-Client-Id).

Vite on WSL /mnt/c: server.watch.usePolling is on so HMR sees Windows-FS writes. Restart npm run dev if the browser still serves a stale module.

Last updated: 2026-08-11