diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 8341fce0..42fed839 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,285 +1,54 @@ -# GitHub Copilot Instructions for react-admin-nestjs +# react-admin-nestjs -## Project Overview +School attendance management system: teachers, students, classes, attendance reports, grades, Yemot phone integration. -This is a full-stack educational management system built with: -- **Frontend**: React 18 with React-Admin 5.3 and Vite 2.7 (JavaScript/JSX) -- **Backend**: NestJS 9 with TypeORM (TypeScript) -- **Database**: MySQL -- **Architecture**: Monorepo with Git submodules for shared utilities - -### Repository Structure - -``` -/client - React Admin frontend application -/server - NestJS backend application -/db - MySQL database configuration and seed data -/client/shared - Git submodule: nra-client (shared client components) -/server/shared - Git submodule: nra-server (shared server modules) -``` - -## Essential Setup Requirements - -### Git Submodules -**CRITICAL**: This project uses Git submodules that MUST be initialized before any development: - -```bash -git submodule update --init --recursive -``` - -The shared submodules contain essential utilities and components. **Never modify code without initializing submodules first**, as this will cause import errors and test failures. - -### Installation - -Backend: -```bash -cd server && yarn install -``` - -Frontend: -```bash -cd client && yarn install -``` - -## Development Workflow +## Stack -### Testing Strategy - -**ALWAYS run tests in this order:** - -1. **Backend tests first** (server directory): - ```bash - cd server && yarn test - ``` - - Framework: Jest with ts-jest - - Expected: 79 test suites, 789 tests - - Pattern: `*.spec.ts` or `*.test.ts` - -2. **Frontend tests second** (client directory): - ```bash - cd client && yarn test - ``` - - Framework: Jest with jsdom - - Expected: 11 test suites, 87 tests - - Pattern: `*.test.js` or `*.spec.js` - -**Do not proceed with deployment or Docker builds if tests fail.** +- **Frontend**: React-Admin (JSX) + Vite — `/client` +- **Backend**: NestJS (TypeScript) + TypeORM — `/server` +- **Database**: MySQL +- **Shared submodules**: `client/shared` -> `nra-client`, `server/shared` -> `nra-server` -### Building +Initialize before first use: `git submodule update --init --recursive` +Never modify code in `client/shared` or `server/shared` directly — those are separate repos. -Backend production build: -```bash -cd server && yarn build -``` +## Testing -Frontend production build: -```bash -cd client && yarn build ``` - -## Coding Standards & Conventions - -### Backend (NestJS/TypeScript) - -1. **Entity Configuration Pattern**: - - Place TypeORM entities in `/server/src/db/entities/` - - Create entity modules in `/server/src/entity-modules/` following the `*.config.ts` pattern - - Register new entities in `/server/src/entities.module.ts` - - Use dependency injection consistently - -2. **TypeScript Standards**: - - Use TypeScript for all server code - - Follow NestJS module/controller/service pattern - - Use decorators appropriately (`@Controller`, `@Injectable`, etc.) - - Maintain proper typing throughout - -3. **Testing**: - - Test files should be colocated with source files using `*.spec.ts` pattern - - Use NestJS testing utilities - - Mock external dependencies - -### Frontend (React/JavaScript) - -1. **Entity Definition Pattern**: - - Create entity definitions in `/client/src/entities/` as `.jsx` files - - Register resources in `/client/src/App.jsx` with proper icons and menu groups - - Follow React-Admin conventions for List, Create, Edit, Show components - -2. **Code Style**: - - Use JSX for React components - - Prefer functional components with hooks - - Use Material-UI components consistently - - Follow existing component structure patterns - -3. **Shared Components**: - - Reuse components from `/client/shared/components/` - - Use established providers (dataProvider, authProvider, i18nProvider) - - Leverage utility functions from `/client/shared/utils/` - -4. **Testing**: - - Test files should be colocated using `*.test.js` pattern - - Use Jest with jsdom for component testing - -## Docker Development - -### Configuration Files -- `docker-compose.yml` - Base production configuration -- `docker-compose.override.yml.template` - Development overrides template (copy to `.yml` for use) - -### Port Assignments -- Frontend (Vite): Port `3000` with HMR on `24678` (HMR port MUST be exposed) -- Backend (NestJS): Port `3001` (maps to container 3000) -- MySQL: Port `3306` -- PhpMyAdmin: Port `8080` - -### Volume Strategy -Docker is configured to reuse host `node_modules`: - -```yaml -volumes: - - ./client:/app - - /app/node_modules # Exclude: use container's node_modules - - /app/dist # Exclude: use container's dist +cd server && yarn test # Jest + ts-jest +cd client && yarn test # Jest + jsdom ``` -**Benefits**: Faster startup, reduced disk usage, consistent dependencies - -### Running Development Environment - -1. Copy templates: - ```bash - cp docker-compose.override.yml.template docker-compose.override.yml - cp .env.template .env - ``` - -2. Configure environment variables in `.env` - -3. Start services: - ```bash - docker-compose up -d - ``` - -## Special Considerations - -### Puppeteer for PDF Generation - -The backend uses Puppeteer for PDF report generation: -- Primary use: `server/shared/utils/report/markup-to-pdf.generator.ts` -- Chromium is installed in the Docker container -- Keep Puppeteer configuration unless it causes blocking issues -- The `PUPPETEER_EXECUTABLE_PATH` is set to `/usr/bin/chromium-browser` - -### Internationalization - -- Primary language: Hebrew (RTL support enabled) -- Translation keys in `/client/src/domainTranslations.js` -- i18n provider: `/client/shared/providers/i18nProvider.js` - -### Authentication & Authorization - -- JWT-based authentication -- Auth module: `/server/shared/auth/auth.module.ts` -- Permission utilities: `/client/shared/utils/permissionsUtil.js` -- Configure admin credentials via environment variables - -### External Integrations - -**Yemot Phone System Integration**: -- Chain configurations in `/server/src/yemot/` -- Used for phone-based attendance reporting and teacher interactions - -## Common Tasks - -### Adding a New Entity - -1. **Backend**: - - Create TypeORM entity in `/server/src/db/entities/MyEntity.ts` - - Create config in `/server/src/entity-modules/my-entity.config.ts` - - Register in `/server/src/entities.module.ts` - -2. **Frontend**: - - Create entity definition in `/client/src/entities/my-entity.jsx` - - Register resource in `/client/src/App.jsx` - - Add translations to `/client/src/domainTranslations.js` - -3. **Test both sides** before considering the task complete - -### Creating Reports - -1. **Backend generator**: `/server/src/reports/myReport.ts` -2. **Frontend component**: `/client/src/reports/myReportButton.jsx` -3. Use Puppeteer for PDF generation if needed - -### Updating Shared Utilities - -**IMPORTANT**: The `/client/shared` and `/server/shared` directories are Git submodules pointing to separate repositories: -- Client shared: https://github.com/buzz-code/nra-client -- Server shared: https://github.com/buzz-code/nra-server - -**Do not modify these directly** unless you intend to update the upstream repositories. - -## Troubleshooting - -### "Module Not Found" Errors -**Solution**: Initialize git submodules -```bash -git submodule update --init --recursive +Start via Docker (from the multi-repo-codespace bootstrap, one project at a time): ``` - -### Docker Volume Issues -**Solution**: Ensure volume exclusions are in docker-compose configuration: -```yaml -volumes: - - /app/node_modules - - /app/dist +cp .env.template .env +cp docker-compose.override.yml.template docker-compose.override.yml +docker-compose up -d client server database ``` -### HMR Not Working in Docker -**Solution**: Expose port 24678 in `docker-compose.override.yml`: -```yaml -ports: - - "24678:24678" -``` +## Code Patterns -### Puppeteer PDF Failures -**Solution**: Verify Chromium installation in container and `PUPPETEER_EXECUTABLE_PATH` environment variable +**Server entity (NestJS/TypeORM):** +1. Create TypeORM entity in `server/src/db/entities/` +2. Create config in `server/src/entity-modules/.config.ts` +3. Register in `server/src/entities.module.ts` -## Pre-Commit Checklist +**Client entity (React-Admin):** +1. Create `client/src/entities/.jsx` with List/Create/Edit/Show +2. Register resource in `client/src/App.jsx` +3. Add translations to `client/src/domainTranslations.js` -When making changes: -- [ ] Git submodules are initialized -- [ ] Dependencies installed (both client and server) -- [ ] Backend tests pass -- [ ] Frontend tests pass -- [ ] Code follows established patterns -- [ ] New entities registered in both frontend and backend -- [ ] Translations updated if adding UI strings -- [ ] Documentation updated if changing workflows +Use shared components from `client/shared/components/` and utilities from `client/shared/utils/`. +Auth: JWT via `server/shared/auth/`. Permissions: `client/shared/utils/permissionsUtil.js`. -## Environment Variables +## Coding Guidelines -Key environment variables to configure (see `.env.template`): -- `MYSQL_HOST`, `MYSQL_USER`, `MYSQL_PASSWORD`, `MYSQL_DATABASE` -- `JWT_SECRET` -- `ADMIN_USER`, `ADMIN_PASSWORD`, `ADMIN_NAME` -- `SMTP_USER`, `SMTP_PASSWORD` (for email functionality) -- `DOMAIN_NAME` (for deployments) -- `REACT_APP_API_URL` (frontend API endpoint) +> Derived from Andrej Karpathy's observations on common LLM coding pitfalls. -## Documentation References +**1. Think Before Coding** — Surface assumptions and tradeoffs before writing code. If something is unclear, ask — do not guess silently. -- Project Index: `/project-index.md` - Comprehensive file and module reference -- Agent Workflow: `/AGENTS.md` - Detailed development workflow guide -- New Project Checklist: `/new-project-checklist.md` - Template for creating similar projects -- Backend API: Swagger documentation at `/api` endpoint (when running) -- React-Admin: https://marmelab.com/react-admin/ -- NestJS: https://docs.nestjs.com/ +**2. Simplicity First** — Write the minimum code that solves the problem. No speculative features, abstractions, or flexibility that was not requested. If 200 lines could be 50, rewrite it. -## Key Principles +**3. Surgical Changes** — Touch only what is necessary. Do not improve adjacent code or formatting. Match existing style. Every changed line must trace to the user's request. -1. **Minimal Changes**: Make surgical, precise modifications -2. **Test-First**: Always run existing tests before and after changes -3. **Follow Patterns**: Use existing code structure as a guide -4. **Git Submodules**: Never forget to initialize them -5. **Sequential Testing**: Backend tests → Frontend tests → Docker build -6. **Documentation**: Keep project documentation in sync with code changes +**4. Goal-Driven Execution** — Define verifiable success criteria before starting. For multi-step tasks, write a brief plan with checkpoints and verify each one. \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index d9b33c05..42fed839 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,245 +1,54 @@ -# Agent Workflow Documentation +# react-admin-nestjs -## Project Structure +School attendance management system: teachers, students, classes, attendance reports, grades, Yemot phone integration. -This is a full-stack application built with: -- **Backend**: NestJS (TypeScript) - located in `/server` -- **Frontend**: React with React-Admin (JavaScript/JSX) - located in `/client` -- **Shared Code**: Git submodules containing shared utilities - - `client/shared` - [nra-client](https://github.com/buzz-code/nra-client) - - `server/shared` - [nra-server](https://github.com/buzz-code/nra-server) +## Stack -## Initial Setup +- **Frontend**: React-Admin (JSX) + Vite — `/client` +- **Backend**: NestJS (TypeScript) + TypeORM — `/server` +- **Database**: MySQL +- **Shared submodules**: `client/shared` -> `nra-client`, `server/shared` -> `nra-server` -### 1. Clone Repository with Submodules -```bash -git clone -cd react-admin-nestjs -git submodule update --init --recursive -``` - -**Important**: The shared submodules MUST be initialized before running tests or building. +Initialize before first use: `git submodule update --init --recursive` +Never modify code in `client/shared` or `server/shared` directly — those are separate repos. -### 2. Install Dependencies +## Testing -Backend: -```bash -cd server -yarn install ``` - -Frontend: -```bash -cd client -yarn install +cd server && yarn test # Jest + ts-jest +cd client && yarn test # Jest + jsdom ``` -## Testing Workflow - -### Backend Tests (NestJS) -```bash -cd server -yarn test -``` -- Test Framework: Jest with ts-jest -- Test Pattern: `*.spec.ts` or `*.test.ts` -- Expected Results: 79 test suites, 789 tests (as of current state) - -### Frontend Tests (React) -```bash -cd client -yarn test +Start via Docker (from the multi-repo-codespace bootstrap, one project at a time): ``` -- Test Framework: Jest with jsdom -- Test Pattern: `*.test.js` or `*.spec.js` -- Expected Results: 11 test suites, 87 tests (as of current state) - -### Test Execution Sequence -1. **Always** run backend tests first -2. Then run frontend tests -3. Do not proceed with deployment or Docker setup if tests fail - -## Docker Development Workflow - -### Configuration Files -- `docker-compose.yml` - Base production configuration -- `docker-compose.override.yml.template` - Development overrides template - -### Port Assignments (Local Development) -Sequential port mapping for services: -- **Frontend (Vite)**: - - Main dev server: `3000` - - HMR (Hot Module Replacement): `24678` ⚠️ **Must be exposed** -- **Backend (NestJS)**: `3001` (maps to container port 3000) -- **MySQL**: `3306` -- **PhpMyAdmin**: `8080` - -### Volume Management for node_modules Reuse - -The Docker setup is optimized to reuse `node_modules` installed on the host machine, preventing duplicate installations inside containers: - -```yaml -volumes: - - ./client:/app # Mount source code - - /app/node_modules # Exclude: use container's node_modules - - /app/dist # Exclude: use container's dist -``` - -**Benefits**: -- Faster container startup -- Reduced disk space usage -- Consistent dependency versions between host and container - -### Running Docker Development Environment - -1. Copy the override template: -```bash -cp docker-compose.override.yml.template docker-compose.override.yml -``` - -2. Set up environment: -```bash cp .env.template .env -# Edit .env with your configuration -``` - -3. Start services: -```bash -docker-compose up -d -``` - -4. View logs: -```bash -docker-compose logs -f frontend -docker-compose logs -f backend -``` - -## Puppeteer Configuration - -Puppeteer is used for PDF generation in reports and is properly configured in the backend. - -### Dockerfile Setup -The backend Dockerfile includes Chromium browser installation: -```dockerfile -RUN apk add --no-cache \ - udev \ - ttf-freefont \ - chromium -ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser -``` - -### Usage Location -- Primary use: `server/shared/utils/report/markup-to-pdf.generator.ts` -- Purpose: Convert HTML markup to PDF reports -- Configuration: Sandboxed mode with proper flags for Docker environment - -### Maintenance Notes -- Keep Puppeteer in the workflow unless it causes blocking issues -- The Chromium version is managed by Alpine package manager -- PDF generation tests are included in the test suite - -## Frontend Constants and Configuration - -### Vite Configuration -Located in `client/vite.config.js`: - -```javascript -server: { - host: '0.0.0.0', - port: Number(process.env.PORT || 3000), - hmr: { - overlay: true, - port: 24678, // HMR WebSocket port - timeout: 1000, - clientPort: 24678, - host: 'localhost', - }, -} -``` - -### Important Notes -- HMR (Hot Module Replacement) requires port **24678** to be exposed -- The main dev server port defaults to 3000 but can be configured via `PORT` env var -- API URL is configured via `REACT_APP_API_URL` environment variable - -## CI/CD Considerations - -### Pre-Deployment Checklist -1. ✅ All backend tests pass -2. ✅ All frontend tests pass -3. ✅ Git submodules are up to date -4. ✅ Docker containers build successfully -5. ✅ Environment variables are properly configured - -### Build Commands - -Backend production build: -```bash -cd server -yarn build +cp docker-compose.override.yml.template docker-compose.override.yml +docker-compose up -d client server database ``` -Frontend production build: -```bash -cd client -yarn build -``` +## Code Patterns -## Development Best Practices +**Server entity (NestJS/TypeORM):** +1. Create TypeORM entity in `server/src/db/entities/` +2. Create config in `server/src/entity-modules/.config.ts` +3. Register in `server/src/entities.module.ts` -1. **Always initialize submodules** before starting work -2. **Run tests locally** before committing -3. **Use Docker override** for local development customization -4. **Keep node_modules** on host machine for faster development -5. **Expose HMR port 24678** when running frontend in Docker -6. **Sequential port assignment** prevents conflicts in local development +**Client entity (React-Admin):** +1. Create `client/src/entities/.jsx` with List/Create/Edit/Show +2. Register resource in `client/src/App.jsx` +3. Add translations to `client/src/domainTranslations.js` -## Troubleshooting +Use shared components from `client/shared/components/` and utilities from `client/shared/utils/`. +Auth: JWT via `server/shared/auth/`. Permissions: `client/shared/utils/permissionsUtil.js`. -### Tests Fail with Module Not Found -**Solution**: Initialize git submodules -```bash -git submodule update --init --recursive -``` +## Coding Guidelines -### Docker Container Can't Find node_modules -**Solution**: Ensure volume exclusions are present in docker-compose configuration -```yaml -volumes: - - /app/node_modules - - /app/dist -``` +> Derived from Andrej Karpathy's observations on common LLM coding pitfalls. -### HMR Not Working in Docker -**Solution**: Ensure port 24678 is exposed in docker-compose.override.yml -```yaml -ports: - - "24678:24678" -``` +**1. Think Before Coding** — Surface assumptions and tradeoffs before writing code. If something is unclear, ask — do not guess silently. -### Puppeteer PDF Generation Fails -**Solution**: Verify Chromium is installed in the container and PUPPETEER_EXECUTABLE_PATH is set correctly - -## Project Workflow Summary - -``` -1. Clone Repo → Initialize Submodules - ↓ -2. Install Dependencies (Backend & Frontend) - ↓ -3. Run Tests (Sequential: Backend → Frontend) - ↓ -4. Docker Setup (Copy templates, configure env) - ↓ -5. Start Development (docker-compose up) - ↓ -6. Develop & Test (Iterate with HMR) - ↓ -7. Build & Deploy (Production builds) -``` +**2. Simplicity First** — Write the minimum code that solves the problem. No speculative features, abstractions, or flexibility that was not requested. If 200 lines could be 50, rewrite it. -## Additional Resources +**3. Surgical Changes** — Touch only what is necessary. Do not improve adjacent code or formatting. Match existing style. Every changed line must trace to the user's request. -- Backend Swagger API Documentation: `/api` endpoint (when running) -- React-Admin Documentation: https://marmelab.com/react-admin/ -- NestJS Documentation: https://docs.nestjs.com/ +**4. Goal-Driven Execution** — Define verifiable success criteria before starting. For multi-step tasks, write a brief plan with checkpoints and verify each one. \ No newline at end of file