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

# 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/` contains module, controller, resolver, and service for each resource.
- Client: `admin-ui/src/` for React components (e.g., PostCreate, PostList, etc.), `admin-ui/src/api/` 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.