rg_backend_academy/AGENTS.md

Agent Instructions

These instructions apply to AI coding agents working in this repository.

Project context

This is an educational full-stack project focused on backend development. The expected stack is Node.js, React, and a local PostgreSQL database on Ubuntu.

The repository may start with only documentation and gradually grow into a structured application. Prefer small, understandable changes that are suitable for students learning backend engineering.

Communication

• Reply to the user in Czech unless the user explicitly asks for another language.
• Write documentation, code comments, commit messages, and generated project text in English.
• Keep explanations practical and tied to the current codebase.

Engineering guidelines

• Read the existing files before making assumptions about project structure.
• Follow existing conventions once code is added.
• Keep changes scoped to the requested task.
• Prefer clear, boring solutions over clever abstractions.
• Add comments only when they clarify non-obvious behavior.
• Do not commit local secrets, .env files, database dumps, or generated dependency directories.

Expected local tools

• Node.js 22 or newer
• PostgreSQL installed locally
• Git
• npm unless the repository later standardizes on another package manager

Suggested application conventions

When application code is introduced, prefer this layout unless the project chooses another structure:

apps/backend
apps/web
packages/shared
docs

For backend work, include:

• Explicit environment variable validation.
• Database migrations instead of manual schema changes.
• Focused automated tests for controllers, services, and database behavior.
• Clear separation between HTTP handlers, business logic, and persistence.

For frontend work, include:

• React components with clear responsibilities.
• Typed API contracts shared with or generated from the backend when practical.
• Accessible forms, loading states, and error states.

Database guidance

• Use a dedicated local database user for the application.
• Do not use the postgres superuser as the application user.
• Store local connection strings in .env.
• Keep schema changes in migrations once a migration tool is selected.

Recommended local development database URL:

DATABASE_URL="postgresql://rg_academy:rg_academy@localhost:5432/rg_academy_dev"

Verification

Before finishing code changes, run the relevant checks when they exist:

npm run lint
npm run test
npm run build

If a command is missing because the project has not been scaffolded yet, state that clearly in the final response.