toucan-codebase-architecture

name	toucan-codebase-architecture
description	React SPA codebase architecture guide. Use when scaffolding a new feature, placing files, wiring up an API hook, adding a Zustand store, protecting a route, handling errors, or optimising performance. Covers the complete vertical slice from API to UI using a feature-driven architecture. Triggers on any task involving project structure, API design, state management, security, components, error handling, performance, deployment, or testing in a React + Vite + React Query codebase.
license	MIT
metadata	{"author":"thinkthroo","version":"1.0.0","series":"amazon-rainforest"}

Toucan — Codebase Architecture

A comprehensive architecture guide for production-grade React SPAs, demonstrated through a feature-driven architecture with React, Vite, React Query, Zustand, and React Hook Form.

All code examples use generic Resource, createResource, useResources, etc. so the patterns transfer cleanly to any domain — swap the entity name for your own.

---

When to Apply

Reference these guidelines when:

• Scaffolding a new feature end-to-end (API hook → store → UI)
• Deciding where a new file belongs
• Writing or reviewing React Query hooks and API clients
• Creating or refactoring Zustand stores
• Protecting routes or implementing authorization
• Adding error handling and observability
• Optimising re-renders or bundle size
• Setting up tests or CI/CD pipelines

---

Rule Categories by Priority

Priority	Category	Impact	Prefix	Rule file
1	Project Structure	CRITICAL	struct-	rules/project-structure.md
2	API Layer	CRITICAL	api-	rules/api-layer.md
3	Security	HIGH	sec-	rules/security.md
4	State Management	MEDIUM-HIGH	state-	rules/state-management.md
5	Component Structure	MEDIUM	comp-	rules/component-structure.md
6	Error Handling	MEDIUM	err-	rules/error-handling.md
7	Performance	LOW-MEDIUM	perf-	rules/performance.md
8	Project Standards	LOW-MEDIUM	standards-	rules/project-standards.md
9	Deployment	LOW	deploy-	rules/deployment.md
10	Testing	LOW	test-	rules/testing.md

---

Quick Reference

1. Project Structure (CRITICAL)

• struct-directory-layout — Feature-driven layout with src/features/ as the core
• struct-data-flow — Unidirectional: shared → features → app
• struct-feature-modules — One self-contained module per feature
• struct-no-cross-feature — Features never import from other features
• struct-file-placement — Decision table for where every type of file belongs

2. API Layer (CRITICAL)

• api-single-client — One pre-configured Axios instance in src/lib/api-client.ts
• api-interceptors — Auth headers, response unwrapping, and error notifications globally
• api-query-pattern — Fetcher function + queryOptions factory + useQuery hook
• api-mutation-pattern — Zod schema + mutation function + cache invalidation hook
• api-prefetching — Prefetch query data on hover for snappy navigation

3. Security (HIGH)

• sec-token-storage — Tokens stored in HttpOnly cookies; never localStorage
• sec-auth-config — react-query-auth wraps all auth mutations and state
• sec-protected-routes — ProtectedRoute guard wraps all authenticated routes
• sec-rbac — Role-based access with useAuthorization hook and Authorization component
• sec-pbac — Policy-based access for resource-level permission checks
• sec-xss-prevention — Always sanitize user-generated HTML with DOMPurify

4. State Management (MEDIUM-HIGH)

• state-categories — Five distinct categories: component, application, server cache, form, URL
• state-component-state — Start with useState/useReducer; elevate only when needed
• state-global-ui — Zustand for global UI state (notifications, modals, theme)
• state-server-cache — React Query exclusively for all server data; never Zustand for API data
• state-form-state — React Hook Form + Zod for all form state and validation
• state-url-state — React Router params and search params for bookmarkable state
• state-decision-tree — Decision tree for choosing the right state tool

5. Component Structure (MEDIUM)

• comp-shared-vs-feature — Shared in src/components/, feature-scoped in src/features/<f>/components/
• comp-no-nested-render — Never write nested render functions; extract into components
• comp-composition-pattern — Use children/slots instead of excessive props
• comp-tailwind-cn — Tailwind CSS + cn() helper for all styling
• comp-shadcn-pattern — ShadCN UI for component library; components are owned code
• comp-form-pattern — Abstracted Form component built on React Hook Form

6. Error Handling (MEDIUM)

• err-central-interceptor — All API errors caught in Axios response interceptor
• err-error-boundaries — App-level, route-level, and component-level error boundaries
• err-query-errors — React Query isError state for inline error display
• err-sentry — Sentry for production error tracking with source maps

7. Performance (LOW-MEDIUM)

• perf-code-splitting — Route-level lazy() imports for bundle splitting
• perf-state-optimizations — Split state, keep state local, lazy initializers
• perf-children-optimization — Pass stable children to avoid re-renders
• perf-image-optimization — Lazy loading, WEBP format, responsive srcset
• perf-prefetching — Prefetch on hover; route loaders for data-before-render

8. Project Standards (LOW-MEDIUM)

• standards-eslint — ESLint with import restriction rules and naming conventions
• standards-prettier — Prettier with format-on-save
• standards-typescript — TypeScript strict mode; no any
• standards-husky — Husky + lint-staged pre-commit hooks
• standards-absolute-imports — @/ prefix for all src/ imports

9. Deployment (LOW)

• deploy-platform — Recommended platforms (Vercel, Netlify, AWS CloudFront)
• deploy-env-vars — Validated env module; never import.meta.env directly
• deploy-ci-cd — CI/CD pipeline: lint → typecheck → test → build → E2E → deploy
• deploy-caching — Long-lived static assets; no-cache HTML
• deploy-preview — Preview deployments for every pull request

10. Testing (LOW)

• test-strategy — Integration-first: unit < integration < E2E
• test-unit — Pure functions, utilities, and complex isolated components
• test-integration — Every feature route tested with MSW-mocked API
• test-e2e — Critical user journeys with Playwright
• test-msw — MSW for HTTP-level mocking; never mock modules directly

---

How to Use

Read a rule file for the detailed explanation and code examples:

rules/project-structure.md    — struct-* rules
rules/api-layer.md            — api-* rules
rules/security.md             — sec-* rules
rules/state-management.md     — state-* rules
rules/component-structure.md  — comp-* rules
rules/error-handling.md       — err-* rules
rules/performance.md          — perf-* rules
rules/project-standards.md    — standards-* rules
rules/deployment.md           — deploy-* rules
rules/testing.md              — test-* rules

Each rule contains:

• Why it matters — the problem it prevents
• Bad example — what not to do, with explanation
• Good example — the correct pattern, with explanation

---

Full Compiled Document

For all rules expanded in one flat document: AGENTS.md