# AGENTS.md — {{PROJECT_NAME}}

> Project-level agent rules. For full API references, read the files in `docs/`
> (auto-generated by postinstall from the installed package versions).

## What this project is

A fullstack FBCA (Feature-Based Component Architecture) app generated by
`@bloomneo/bloom`. It combines:

- **Frontend**: React + `@bloomneo/uikit` — component library, themes, layouts
- **Backend**: Express + `@bloomneo/appkit` — auth, database, cache, queue, email, etc.
- **Architecture**: Features live in `src/web/features/` (frontend) and
  `src/api/features/` (backend). Each feature is self-contained.

## Where to find the API docs

After `npm install`, these files are in `docs/`:

| File | Contents |
|------|----------|
| `docs/appkit.md` | Full `@bloomneo/appkit` API — all 12 modules, method signatures, examples |
| `docs/appkit-agents.md` | AppKit agent rules — always/never lists, canonical patterns |
| `docs/uikit.md` | Full `@bloomneo/uikit` API — components, hooks, layouts, themes |
| `docs/uikit-agents.md` | UIKit agent rules — always/never lists, import/compose patterns |
| `docs/admin-patterns.md` | This template's patterns — layout routes, admin-api helper, audit, settings |

These are copied from the installed packages on every `npm install`, so they
always match the exact version in use. **Read them before generating code.**

## Project structure

```
src/
├── api/                    # Express backend (AppKit)
│   ├── features/           # One folder per feature
│   │   └── {feature}/
│   │       ├── {feature}.route.ts    # Express routes
│   │       ├── {feature}.service.ts  # Business logic
│   │       └── {feature}.types.ts    # Types
│   ├── lib/                # Shared backend utilities
│   └── server.ts           # Express app entry point
└── web/                    # React frontend (UIKit)
    ├── features/           # One folder per feature
    │   └── {feature}/
    │       ├── pages/      # Auto-discovered routes (file → URL)
    │       ├── components/ # Feature-specific components
    │       └── hooks/      # Feature-specific hooks
    ├── shared/             # Reused across features
    └── App.tsx             # Root app
```

## Key conventions

### Backend (AppKit)
- Always use `xxxClass.get()` — never `new SomethingClass()`
- Wrap async routes: `error.asyncRoute(async (req, res) => { ... })`
- Mount `error.handleErrors()` last in the Express stack
- Auth chain: `auth.requireLoginToken()` THEN `auth.requireUserRoles(['role.level'])`
- Never read `process.env` directly in features — use `configClass`

### Frontend (UIKit)
- Wrap app in `<ThemeProvider>` — required for all UIKit components
- Wrap app in `<ToastProvider>` — required for `useToast()`
- Auto-routing: files in `features/*/pages/` become routes automatically
- Use `useTheme()` for theme switching, `useBreakpoint()` for responsive logic

## Environment setup

Copy `.env.example` to `.env` and fill in:

```bash
BLOOM_AUTH_SECRET=<min 32 chars>     # required — JWT signing
DATABASE_URL=postgresql://...         # required — Prisma connection
BLOOM_SECURITY_CSRF_SECRET=<32 chars> # recommended
BLOOM_SECURITY_ENCRYPTION_KEY=<64 hex> # recommended
REDIS_URL=redis://...                 # optional — distributed cache/queue
```

## Adding a new feature

```bash
# Backend: src/api/features/orders/
# Frontend: src/web/features/orders/pages/index.tsx → route /orders
```

See `docs/appkit.md` for backend API, `docs/uikit.md` for frontend components.