How yukionishi1129/bulletproof-react works
Project Type and Purpose
• This is a front-end, single-page React application that serves as an opinionated, “bulletproof” architecture for production-ready React projects.
• It provides a scalable file structure, built-in patterns (features, API layer, state management, testing, styling), and example code for real-world use cases.
• There is no backend code here; instead, the app relies on external HTTP APIs (consumed via axios/react-query) and uses MSW (Mock Service Worker) for local testing.
High-Level Components
a. Public Layer
• /public: static assets (index.html, manifest.json, mockServiceWorker.js), redirects, robots.txt.
b. Application Shell
• src/index.tsx → initializes React, React-Query provider, custom providers (src/providers/app.tsx), global styles (index.css), and mounts <App />.
c. Core Providers & Config
• src/providers: top-level contexts (e.g., Theme, React-Query client).
• craco.config.js & tailwind.config.js: build tooling and styling.
d. Routing
• src/routes: defines public vs protected route sets.
• <App /> (in src/App.tsx): wraps routes in layouts.
e. Feature Modules
• src/features/<domain>: each feature folder (auth, discussions, comments, users, teams, misc) contains:
• api/*: axios calls via src/lib/axios.ts + wrapped in React-Query hooks
• components/*: presentational or form UI
• routes/*: route components
• types: domain types
f. UI Components & Styling
• src/components: reusable UI elements (Buttons, Dialogs, Tables, Spinner, etc.) with Storybook stories.
g. State Management
• src/stores: lightweight Zustand stores (e.g., notifications).
• React-Query (src/lib/react-query.ts) for server state.
h. Utilities & Lib
• src/lib: auth helpers, authorization HOCs, axios instance, react-query config.
• src/utils: formatting, lazy imports, storage.
i. Testing
• Unit tests: __tests__, cypress for end-to-end, MSW mocks under src/test/server.
• CI workflow in .github/workflows/ci.yml.
j. Documentation
• docs/: markdown guidelines on architecture, styling, state management, API layer, error handling, deployment.
Relationships & Data Flow
1. User interacts with UI (Components in src/components or feature UIs).
2. Routed by React Router (src/routes) to a feature route.
3. Components trigger data fetching via React-Query hooks / Zustand actions.
4. React-Query uses src/lib/axios.ts to call external REST endpoints.
5. Responses update React-Query cache (server state) and/or Zustand stores (client state).
6. State changes re-render UI.
7. Notifications are managed by stores/notifications.ts and shown via Notifications component.
8. E2E tests in Cypress intercept network via MSW (public/mockServiceWorker.js) and validate flows.
Key Architectural Patterns
• Feature-based folder structure for domain isolation.
• Separation of concerns: UI components vs feature logic vs API.
• React-Query for async server state; Zustand for local/global client state.
• Pluggable component library (Atomic Elements, Forms).
• Storybook for visual component testing and documentation.
• MSW for reliable testing environment.
• CRACO for zero-eject configuration.