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/:

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:

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

# 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.