[Rules] Consolidated project structure, conventions, and workflow documentation

[yuval-hazaz]

Rules

• The project uses a monorepo structure with two main components: a backend (server) built with Node.js/NestJS and a frontend (admin-ui) built with React and React-Admin.
• The backend utilizes NestJS (TypeScript), Prisma ORM (PostgreSQL), class-validator, JWT and HTTP Passport authentication, GraphQL and REST APIs, and Docker for containerization.
• The frontend is a React application bootstrapped via create-react-app and uses react-admin as the admin interface framework.
• The Prisma ORM models define entities: User, Post, Author, Tag, Story. Entities are referenced with @relation in Prisma and cross-related in both server and admin-ui types.
• The backend enforces global prefix /api for all REST/GraphQL endpoints.
• Authorization and authentication are implemented using nest-access-control, custom JWT/Basic strategies, ABAC (attribute-based access control), and guarding endpoints by default except specific system endpoints (like health check).
• File structure conventions:
  • Server: server/src/<entity> contains module, controller, resolver, and service for each resource.
  • Client: admin-ui/src/<resource> for React components (e.g., PostCreate, PostList, etc.), admin-ui/src/api/<resource> for TypeScript types for API communication.
  • Utilities go into src/util in both projects.
  • Docker-related files, configuration, and environment live in each root directory or in /configuration for frontend nginx.
  • Test specs are placed near their respective code; tests follow .spec.ts(x) naming for server, .test.ts(x) for frontend.
• Naming conventions:
  • TypeScript classes/files use camelCase for variables and PascalCase for types/classes/components/files.
  • SASS/SCSS CSS classes use BEM-like block syntax and custom CSS variables for consistency.
  • API endpoints and GraphQL schema are camelCased.
  • Environment variables are upper snake case (e.g., REACT_APP_SERVER_URL, DB_URL).
  • Generated types and base code by Amplication are prefixed/commented as such and should not be manually edited.
• To run the backend:
  • Copy .env from example or define all needed variables. Use the provided docker-compose scripts for local dev (npm run docker:dev).
  • Generate the Prisma client with npm run prisma:generate in server/.
  • Migrate/init the database: npm run db:init, bring up the server with npm run start or with docker-compose.
• To run the frontend:
  • Copy/setup .env, edit REACT_APP_SERVER_URL to match backend.
  • Install dependencies: npm install inside admin-ui/.
  • Start development server: npm start.
  • Build production: npm run build.
• To run tests:
  • Backend: npm run test in server/ (Jest).
  • Frontend: npm run test in admin-ui/ (react-scripts with Jest and react-testing-library.)
• To run the formatter:
  • The project uses Prettier. The ignore patterns are in .prettierignore, and the main files to be formatted are TypeScript, JSX, and SCSS files.
  • Use VSCode with Format on Save or run Prettier via CLI if configured.
• To run the linter:
  • ESLint is configured via eslintConfig in frontend package.json and implied for backend via NestJS defaults.
  • Typical command: npm run lint or use IDE integration.
• Docker images are built multi-stage for both backend and frontend, separating build and runtime stages, using production user and optimized image size.
• All API endpoints (except explicitly public/health) must be secured, have validation, and conform to OpenAPI/Swagger docs automatically generated at /api.
• Git ignored files/folders are driven by both server/.gitignore and admin-ui/.gitignore: ignore build outputs, environment/secret files, and node_modules.
• Static assets and configuration (robots.txt, manifest.json, nginx.conf, index.html) follow web standards and best SEO/security practices.
• Frontend deployment serves the build from NGINX as configured; backend exposes service on port 3000 or defined by $PORT.
• The frontend relies on a functioning backend for full operation (must start both for local dev).
• Compose files (docker-compose.yml and docker-compose.dev.yml) define how services (API, DB, migrations) orchestrate.
• All custom environment variables must be documented and their use traced to specific logic/config sections.
• Public endpoints must be explicitly decorated with Public decorator (server).
• Swagger and OpenAPI customization (title, security) are set up through server/src/swagger.ts, with custom CSS and favicon.
• SCSS and CSS are modularized by feature, classes use hyphenated naming, and color palette/theme values come from custom CSS variables under :root.
• Static assets (logo, icons, manifest) must be referenced using %PUBLIC_URL% from React and NGINX configs for safe cross-env builds.
• Root Readme and subproject Readmes must be kept up to date with environment config, sample credentials, setup, and CI instructions.
• CI/CD pipelines run on GitHub Actions (.github/workflows/continuous-integration.yml), running install, build, test per project before allowing deploy.
• Environment-specific deployments (staging/production) are managed via branch and tag conventions, with releases tied to tags on main branch.
• Database changes must be tracked in prisma/migrations/ and applied/migrated in CI/CD.
• Slugs for Authors, Posts, Tags, and Stories are generated via the slugify package for SEO-friendly URLs and stored on create/update.
• When updating types/models, always sync both backend and frontend definitions.
• Avoid editing files directly in /base folders or other generated-code sections; prefer using extension/inheritance or documented customization hooks.
• Adhere to DRY (Don't Repeat Yourself) in utility/helpers and data-fetching logic for both backend and frontend.
• Any added third-party libraries must be added to the respective package.json and, if type definitions are missing, to devDependencies via @types.
• Health checks are implemented via a dedicated resource (/_health), inheriting from HealthControllerBase with full NestJS module structure.
• Interceptors and decorators must follow standard patterns, be placed in interceptors/ and decorators/ folders, respectively, and be tested.
• Test files must accurately mock/prisma services and expect both positive and negative flow, not just happy path.
• When adding new features, update both the entity model, API types, CRUD endpoints, and admin-ui components.
• Pull requests must be CI-green (install, build, test pass) before merge.
• Code formatting/style issues should be addressed before commit using Prettier/ESLint; don't ignore linter hints for both TS and JS(X) code.
• Sensitive values and credentials are never hardcoded—always use env vars and secrets manager integrations for production.
• All environment variable/documentation changes must be reflected in the main README and relevant subproject README files.
• The project aims to be cloud-native, 12-factor compliant, and portable across local, cloud, and CI/CD environments.
• Static files for SEO (manifest, robots.txt, favicon, etc.) should always be present and valid in production builds.