| 2 |
GRANTED
|
project.view
|
App\Execution\Domain\AgentRun {#1116
-id: Symfony\Component\Uid\UuidV7 {#1090 …}
-feature: App\Feature\Domain\Feature {#1127 …}
-agentProfile: App\Agent\Domain\AgentProfile {#1135 …}
-agentNameSnapshot: "Implementer"
-agentTypeSnapshot: App\Agent\Domain\AgentType {#1095 …}
-agentExecutableSnapshot: "claude"
-agentDefaultArgumentsSnapshot: []
-agentMaxRuntimeSecondsSnapshot: 14400
-preferredRunnerIdSnapshot: null
-runner: null
-type: App\Execution\Domain\AgentRunType {#1098 …}
-status: App\Execution\Domain\AgentRunStatus {#1102 …}
-promptSnapshot: """
You are implementing feature HIR-1: Grundsystem mit Authentifizierung, Benutzerverwaltung und Rollen aufbauen\n
\n
Repository: Test-Agent\n
Base branch: main\n
Feature branch: feature/HIR-1-grundsystem-mit-authentifizierung-benutzerverwaltu\n
\n
The branch is already checked out. AGENTS.md and CLAUDE.md in the repository contain the complete\n
project instructions; follow them.\n
\n
## Feature\n
\n
Als Administrator möchte ich Benutzer der Bewerberplattform verwalten können und als Benutzer möchte ich mich sicher an der Anwendung anmelden können, damit die Plattform eine belastbare technische Grundlage für alle weiteren Recruiting-Funktionen besitzt.\n
\n
Im Rahmen dieser Story soll die grundlegende Anwendungsstruktur aufgebaut werden. Dazu gehören Authentifizierung, Benutzerverwaltung, Rollen und Berechtigungen sowie ein grundlegendes geschütztes Backend bzw. Dashboard.\n
\n
Die Architektur soll so ausgelegt sein, dass später weitere Module wie Stellen, Bewerber, Bewerbungen, Dokumente, Kommunikation und Mandanten ergänzt werden können, ohne die Grundstruktur wesentlich verändern zu müssen.\n
\n
## Technical description\n
\n
\n
\n
## Acceptance criteria\n
\n
Die Anwendung besitzt eine persistente Datenbankanbindung.\n
Es existiert eine User-Entität bzw. ein entsprechendes Benutzer-Datenmodell.\n
Ein Benutzer besitzt mindestens:\n
eindeutige ID\n
Vorname\n
Nachname\n
E-Mail-Adresse\n
Passwort-Hash\n
Rolle\n
Aktiv/Inaktiv-Status\n
Erstellungsdatum\n
Änderungsdatum\n
Passwörter werden ausschließlich sicher gehasht gespeichert.\n
Benutzer können sich mit E-Mail-Adresse und Passwort anmelden.\n
Nicht authentifizierte Benutzer können geschützte Bereiche nicht aufrufen.\n
Benutzer können sich abmelden.\n
Nach erfolgreicher Anmeldung wird ein Dashboard angezeigt.\n
Fehlgeschlagene Anmeldungen zeigen eine neutrale Fehlermeldung an.\n
Es existieren mindestens die Rollen:\n
Administrator\n
Recruiter\n
Administratoren können Benutzer:\n
anzeigen\n
anlegen\n
bearbeiten\n
aktivieren\n
deaktivieren\n
Recruiter haben keinen Zugriff auf die Benutzeradministration.\n
Eine doppelte E-Mail-Adresse darf nicht für mehrere Benutzer verwendet werden.\n
Pflichtfelder werden serverseitig validiert.\n
Sicherheitsrelevante Berechtigungen werden ausschließlich im Backend geprüft und nicht nur im Frontend versteckt.\n
Es existiert ein grundlegendes Navigationslayout für authentifizierte Benutzer.\n
Das Layout enthält mindestens:\n
Dashboard\n
Benutzerverwaltung für Administratoren\n
Benutzerprofil\n
Logout\n
Die Anwendung besitzt eine zentrale Fehlerbehandlung.\n
Konfigurationswerte und Secrets werden nicht fest im Sourcecode hinterlegt.\n
Datenbankschema und Änderungen werden über Migrationen verwaltet.\n
Für Authentifizierung und zentrale Berechtigungsprüfungen existieren automatisierte Tests.\n
Die Anwendung kann nach einem frischen Checkout anhand der Projektdokumentation eingerichtet und gestartet werden.\n
\n
## Architecture\n
\n
# Enterprise Application Architecture Rules\n
\n
The application is a production-grade enterprise system designed for thousands of concurrent users.\n
\n
The preferred technology stack is:\n
\n
* **Symfony** as the backend and authoritative application layer\n
* **React with TypeScript** as the frontend\n
* **Mercure** for real-time updates\n
* **Symfony Messenger** for asynchronous and background processing\n
* A relational database as the authoritative persistent data store\n
* Redis or another distributed cache only where it provides a clear architectural benefit\n
\n
The architecture must support horizontal scaling, multiple application instances, concurrent users, background workers, and real-time collaboration.\n
\n
The system must never be designed like a prototype or single-user application.\n
\n
---\n
\n
# High-Level Architecture\n
\n
Use the following logical architecture:\n
\n
```text\n
┌─────────────────────────────────────┐\n
│ React UI │\n
│ │\n
│ Components / Pages / Features │\n
│ Query Cache / Client State │\n
└─────────────────┬───────────────────┘\n
│\n
│ HTTPS / REST\n
▼\n
┌─────────────────────────────────────┐\n
│ Symfony │\n
│ │\n
│ Controllers / API │\n
│ ↓ │\n
│ Application Services / Use Cases │\n
│ ↓ │\n
│ Domain Logic │\n
│ ↓ │\n
│ Repositories / Infrastructure │\n
└───────────────┬───────┬─────────────┘\n
│ │\n
│ │\n
┌───────▼───┐ └───────────────┐\n
│ Database │ │\n
└───────────┘ │\n
▼\n
┌─────────────────┐\n
│ Symfony Messenger│\n
│ Background Jobs │\n
└─────────────────┘\n
\n
Symfony\n
│\n
│ Publish domain/application events\n
▼\n
┌──────────────┐\n
│ Mercure │\n
└──────┬───────┘\n
│ SSE\n
▼\n
┌──────────────┐\n
│ React Clients│\n
└──────────────┘\n
```\n
\n
Symfony is the **source of truth for all business logic**.\n
\n
React must never contain authoritative business rules that can affect data integrity or permissions.\n
\n
Mercure is responsible for notifying connected clients about changes.\n
\n
The database remains the authoritative source of persisted state.\n
\n
---\n
\n
# Backend Authority\n
\n
Symfony is responsible for:\n
\n
* Authentication\n
* Authorization\n
* Business rules\n
* Validation\n
* Transactions\n
* Persistence\n
* Integrations\n
* Background processing\n
* Audit logging\n
* Event publication\n
* API contracts\n
\n
React is responsible for:\n
\n
* Presentation\n
* Interaction\n
* Local UI state\n
* User workflows\n
* Displaying backend state\n
* Reacting to real-time notifications\n
\n
Never trust the frontend.\n
\n
Every operation must be validated and authorized again on the Symfony backend.\n
\n
---\n
\n
# Symfony Architecture\n
\n
Prefer a layered architecture.\n
\n
Recommended structure:\n
\n
```text\n
src/\n
├── Controller/\n
├── Application/\n
│ ├── Command/\n
│ ├── Query/\n
│ ├── DTO/\n
│ └── Service/\n
├── Domain/\n
│ ├── Entity/\n
│ ├── Event/\n
│ ├── Exception/\n
│ ├── Repository/\n
│ ├── Service/\n
│ └── ValueObject/\n
├── Infrastructure/\n
│ ├── Persistence/\n
│ ├── Messaging/\n
│ ├── Mercure/\n
│ ├── ExternalApi/\n
│ └── Storage/\n
├── Security/\n
└── Shared/\n
```\n
\n
This structure may be adapted to the size of the project, but responsibilities must remain clearly separated.\n
\n
Do not place substantial business logic inside controllers.\n
\n
A controller should typically:\n
\n
1. Receive the request.\n
2. Deserialize and validate input.\n
3. Check authorization.\n
4. Call an application service or use case.\n
5. Return a standardized response.\n
\n
---\n
\n
# Feature-Oriented Design\n
\n
For larger systems, prefer organizing business functionality around domains or features rather than creating huge global service directories.\n
\n
Example:\n
\n
```text\n
src/\n
├── User/\n
├── Project/\n
├── Task/\n
├── Notification/\n
├── Applicant/\n
└── Reporting/\n
```\n
\n
Each module may contain its own:\n
\n
```text\n
Application/\n
Domain/\n
Infrastructure/\n
```\n
\n
Avoid a monolithic `Service` directory containing hundreds of unrelated classes.\n
\n
---\n
\n
# API-First Architecture\n
\n
React communicates with Symfony through explicitly defined APIs.\n
\n
Do not directly couple frontend implementation details to database entities.\n
\n
Use:\n
\n
* Request DTOs\n
* Response DTOs\n
* API resources\n
* Explicit schemas\n
\n
Do not automatically expose Doctrine entities as public API contracts.\n
\n
Database entities and API representations serve different purposes and must be allowed to evolve independently.\n
\n
---\n
\n
# REST API\n
\n
REST is the preferred default communication mechanism.\n
\n
Use predictable resource-oriented endpoints.\n
\n
Examples:\n
\n
```text\n
GET /api/projects\n
GET /api/projects/{id}\n
POST /api/projects\n
PATCH /api/projects/{id}\n
DELETE /api/projects/{id}\n
```\n
\n
Complex commands may use explicit action endpoints when they represent real business operations.\n
\n
Example:\n
\n
```text\n
POST /api/projects/{id}/archive\n
POST /api/applicants/{id}/reject\n
POST /api/tasks/{id}/assign\n
```\n
\n
Do not distort the business model purely to force everything into CRUD semantics.\n
\n
---\n
\n
# API Versioning\n
\n
Public or externally consumed APIs must support controlled evolution.\n
\n
Breaking API changes must not silently affect existing clients.\n
\n
Use explicit versioning where necessary.\n
\n
Example:\n
\n
```text\n
/api/v1/...\n
```\n
\n
Internal APIs may avoid unnecessary versioning when frontend and backend are deployed together, but API contracts must still remain intentional and documented.\n
\n
---\n
\n
# Standard API Responses\n
\n
Keep responses consistent.\n
\n
For resources:\n
\n
```json\n
{\n
"data": {}\n
}\n
```\n
\n
For collections:\n
\n
```json\n
{\n
"data": [],\n
"meta": {\n
"page": 1,\n
"pageSize": 50,\n
"total": 1250\n
}\n
}\n
```\n
\n
For errors:\n
\n
```json\n
{\n
"error": {\n
"code": "PROJECT_NOT_FOUND",\n
"message": "Project could not be found."\n
}\n
}\n
```\n
\n
Validation errors should provide field-level information.\n
\n
---\n
\n
# React Architecture\n
\n
React should be written in TypeScript.\n
\n
Prefer a feature-based structure.\n
\n
Example:\n
\n
```text\n
src/\n
├── app/\n
├── features/\n
│ ├── projects/\n
│ ├── applicants/\n
│ ├── users/\n
│ └── notifications/\n
├── components/\n
├── hooks/\n
├── api/\n
├── auth/\n
├── realtime/\n
├── routing/\n
├── types/\n
└── utils/\n
```\n
\n
Keep feature-specific components within the feature whenever possible.\n
\n
Do not create one giant global component directory containing every component in the application.\n
\n
---\n
\n
# React State\n
\n
Differentiate between:\n
\n
### Server State\n
\n
Data originating from Symfony.\n
\n
Examples:\n
\n
* Users\n
* Projects\n
* Applicants\n
* Tasks\n
* Permissions\n
\n
Prefer a dedicated server-state solution such as:\n
\n
* TanStack Query\n
\n
Server state should not unnecessarily be duplicated into global frontend stores.\n
\n
### UI State\n
\n
Examples:\n
\n
* Modal open/closed\n
* Selected tab\n
* Temporary filter\n
* Sidebar state\n
\n
Keep UI state local whenever possible.\n
\n
### Global Client State\n
\n
Use global state management only where genuinely necessary.\n
\n
Do not create a global store merely because state management exists.\n
\n
---\n
\n
# Real-Time Architecture with Mercure\n
\n
Mercure is the preferred mechanism for real-time updates.\n
\n
Its purpose is to ensure that users see changes made by other users or backend processes without manually refreshing the page.\n
\n
Examples:\n
\n
* User A changes a project.\n
* User B currently has the same project open.\n
* User B should see the updated information automatically.\n
\n
Or:\n
\n
* A background worker completes an import.\n
* Connected users should see the new status immediately.\n
\n
Or:\n
\n
* Another employee creates a new applicant.\n
* Relevant applicant lists should update automatically.\n
\n
---\n
\n
# Mercure Is Not the Source of Truth\n
\n
This rule is critical:\n
\n
**Mercure transports change notifications. It is not the authoritative state store.**\n
\n
Symfony and the database remain authoritative.\n
\n
A Mercure message should typically tell the frontend:\n
\n
> Something changed.\n
\n
The frontend can then either:\n
\n
1. Apply a reliable payload directly.\n
\n
or preferably:\n
\n
2. Invalidate and refetch the affected server state.\n
\n
Example:\n
\n
```text\n
Symfony\n
↓\n
Database transaction\n
↓\n
Successful commit\n
↓\n
Mercure event\n
↓\n
React receives event\n
↓\n
TanStack Query invalidates affected query\n
↓\n
React fetches current authoritative state\n
```\n
\n
This avoids frontend state becoming inconsistent.\n
\n
---\n
\n
# Mercure Event Flow\n
\n
Preferred flow for a write operation:\n
\n
```text\n
React\n
│\n
│ PATCH /api/projects/123\n
▼\n
Symfony\n
│\n
├── Authorization\n
├── Validation\n
├── Business Logic\n
├── Database Transaction\n
└── Commit\n
│\n
▼\n
Application / Domain Event\n
│\n
▼\n
Mercure Publication\n
│\n
▼\n
Connected React Clients\n
│\n
▼\n
Query Invalidation / State Refresh\n
```\n
\n
Never publish the final change event before the database transaction has successfully completed.\n
\n
Users must never receive notifications for transactions that were rolled back.\n
\n
---\n
\n
# Mercure Topics\n
\n
Topics must be deliberate and predictable.\n
\n
Examples:\n
\n
```text\n
/project/123\n
/project/123/tasks\n
/applicants\n
/applicant/456\n
/user/123/notifications\n
/organization/42/projects\n
```\n
\n
Avoid placing every event into one global topic.\n
\n
Users should only subscribe to information relevant to the current screen or workflow.\n
\n
---\n
\n
# Mercure Security\n
\n
Private information must use private Mercure updates.\n
\n
Do not expose internal events through publicly readable topics.\n
\n
Subscription authorization must respect the same permission model as the backend.\n
\n
A user who cannot access an entity through the REST API must not receive its data through Mercure.\n
\n
Never rely on frontend filtering for Mercure security.\n
\n
---\n
\n
# Mercure Event Payloads\n
\n
Events should have predictable structures.\n
\n
Example:\n
\n
```json\n
{\n
"event": "project.updated",\n
"entity": "project",\n
"id": "123",\n
"version": 7,\n
"timestamp": "2026-09-20T15:30:00Z"\n
}\n
```\n
\n
Avoid unnecessarily sending complete entities through every event.\n
\n
Prefer small event payloads when the frontend can refetch authoritative data.\n
\n
Large entities should not continuously be broadcast to many clients.\n
\n
---\n
\n
# Event Types\n
\n
Use meaningful event names.\n
\n
Examples:\n
\n
```text\n
project.created\n
project.updated\n
project.deleted\n
\n
applicant.created\n
applicant.updated\n
applicant.deleted\n
\n
task.assigned\n
task.completed\n
\n
import.started\n
import.progress\n
import.completed\n
import.failed\n
```\n
\n
Do not use vague events such as:\n
\n
```text\n
update\n
changed\n
event\n
message\n
```\n
\n
Events should make their purpose immediately understandable.\n
\n
---\n
\n
# Reconnection and Lost Events\n
\n
Real-time applications must assume connections can be interrupted.\n
\n
Possible causes include:\n
\n
* Laptop sleep\n
* Network interruption\n
* Reverse proxy restart\n
* Browser suspension\n
* Mobile network changes\n
* Mercure restart\n
\n
The application must recover automatically.\n
\n
React must never assume that receiving every Mercure event is guaranteed.\n
\n
After reconnecting, the application should synchronize relevant state again with Symfony.\n
\n
The authoritative REST API must always be capable of reconstructing the correct UI state.\n
\n
---\n
\n
# Multiple Browser Tabs and Clients\n
\n
Assume users may have:\n
\n
* Multiple browser tabs\n
* Multiple browser windows\n
* Multiple devices\n
\n
Changes from one session should propagate to other sessions where relevant.\n
\n
Do not rely exclusively on local frontend state.\n
\n
---\n
\n
# Optimistic Updates\n
\n
Optimistic UI updates may be used where they significantly improve usability.\n
\n
However:\n
\n
1. Symfony remains authoritative.\n
2. The optimistic update must be reversible.\n
3. Failed requests must restore previous state.\n
4. Incoming Mercure events must not corrupt optimistic state.\n
5. Conflict scenarios must be handled.\n
\n
\n
\n
\n
## Coding rules\n
\n
# Enterprise Software Engineering Rules\n
\n
You are developing production-grade enterprise software.\n
\n
Every architectural decision, implementation, UI component, API, database query, background process, and integration must be designed with the assumption that this application may be used by **several thousand concurrent users**.\n
\n
The goal is not merely to make features work. The goal is to build software that feels and behaves like a mature, professionally engineered enterprise product.\n
\n
## Core Engineering Principles\n
\n
Always optimize for:\n
\n
* Maintainability\n
* Scalability\n
* Reliability\n
* Security\n
* Performance\n
* Observability\n
* Testability\n
* Extensibility\n
* Clear architecture\n
* Excellent user experience\n
\n
Never implement a quick workaround when a clean and maintainable solution is reasonably possible.\n
\n
Avoid technical debt unless there is an explicit and documented reason for it.\n
\n
Follow established industry standards, framework conventions, proven architectural patterns, and language-specific best practices.\n
\n
Do not invent custom solutions when a well-established standard or framework mechanism already exists.\n
\n
At the same time, avoid unnecessary abstraction and overengineering. Complexity must solve an actual or foreseeable problem.\n
\n
---\n
\n
# Architecture\n
\n
Keep responsibilities clearly separated.\n
\n
Prefer clear architectural boundaries such as:\n
\n
* Presentation / UI\n
* Application / Use Cases\n
* Domain / Business Logic\n
* Infrastructure\n
* Persistence\n
* External integrations\n
\n
Business logic must not be hidden inside controllers, UI components, database queries, templates, or infrastructure code.\n
\n
Controllers and API endpoints should primarily:\n
\n
1. Validate and authorize the request.\n
2. Delegate work to the appropriate application/service layer.\n
3. Return a well-defined response.\n
\n
Design modules with high cohesion and low coupling.\n
\n
Dependencies should point toward stable abstractions.\n
\n
Do not create circular dependencies.\n
\n
Prefer dependency injection over hidden global state.\n
\n
---\n
\n
# Scalability\n
\n
Always assume the system may eventually process:\n
\n
* Thousands of concurrent users\n
* Large database tables\n
* Millions of records\n
* High API request volumes\n
* Multiple application instances\n
* Multiple workers\n
* Concurrent background jobs\n
\n
Never rely on application-local memory for shared state unless explicitly appropriate.\n
\n
The application must be able to run horizontally across multiple instances.\n
\n
Avoid architecture that requires one specific server instance to process a request.\n
\n
Design operations to be safe under concurrency.\n
\n
Use appropriate:\n
\n
* Transactions\n
* Locking\n
* Optimistic concurrency\n
* Idempotency\n
* Queues\n
* Caching\n
* Pagination\n
* Batch processing\n
\n
where required.\n
\n
Do not load large datasets into memory unnecessarily.\n
\n
Never fetch an unlimited database result set.\n
\n
Every potentially large list must support pagination, cursor-based pagination, filtering, or another appropriate limiting strategy.\n
\n
---\n
\n
# Database\n
\n
Treat the database as a critical shared resource.\n
\n
Avoid:\n
\n
* N+1 queries\n
* Unindexed filtering\n
* Unindexed joins on large datasets\n
* Full table scans\n
* SELECT *\n
* Excessive query counts\n
* Database calls inside loops\n
* Large synchronous bulk operations\n
\n
Consider indexing whenever introducing:\n
\n
* Search fields\n
* Foreign keys\n
* Frequently filtered columns\n
* Frequently sorted columns\n
* High-volume joins\n
\n
Database constraints should enforce important data integrity rules whenever possible.\n
\n
Use transactions when an operation modifies multiple related pieces of data.\n
\n
Migrations must be safe for production environments.\n
\n
Consider the impact of schema changes on large tables and running application instances.\n
\n
Never assume the database is empty or small.\n
\n
---\n
\n
# Performance\n
\n
Performance must be considered during implementation, not added as an afterthought.\n
\n
Avoid premature micro-optimization, but identify obvious scalability bottlenecks before introducing them.\n
\n
Expensive work that does not need to happen synchronously should be handled asynchronously.\n
\n
Examples include:\n
\n
* Email\n
* File processing\n
* Large imports\n
* Large exports\n
* Image processing\n
* Report generation\n
* External synchronization\n
* Batch operations\n
\n
Use caching when it provides meaningful benefit, but always define a valid invalidation strategy.\n
\n
Never introduce caching without understanding when cached data becomes stale.\n
\n
---\n
\n
# APIs\n
\n
APIs must be predictable, consistent, secure, and versionable.\n
\n
Use established HTTP semantics and appropriate status codes.\n
\n
API responses should have consistent structures.\n
\n
Validation errors must be machine-readable.\n
\n
Errors must never expose:\n
\n
* Stack traces\n
* Credentials\n
* Internal infrastructure information\n
* Database internals\n
* Secrets\n
\n
Design APIs so clients can safely retry requests where appropriate.\n
\n
Use idempotency for operations where duplicate requests could cause unwanted side effects.\n
\n
Always consider backward compatibility before changing an existing API contract.\n
\n
Avoid breaking changes whenever possible.\n
\n
---\n
\n
# Security\n
\n
Security is mandatory and part of the architecture.\n
\n
Follow secure-by-default principles.\n
\n
Always validate untrusted input.\n
\n
Always implement authorization server-side.\n
\n
Never rely solely on frontend permission checks.\n
\n
Apply least-privilege principles.\n
\n
Protect against common vulnerabilities including:\n
\n
* SQL injection\n
* XSS\n
* CSRF\n
* SSRF\n
* Broken access control\n
* Insecure direct object references\n
* Command injection\n
* Path traversal\n
* Unsafe file uploads\n
* Mass assignment\n
* Sensitive information disclosure\n
\n
Never hardcode:\n
\n
* Passwords\n
* API keys\n
* Tokens\n
* Certificates\n
* Private keys\n
* Connection secrets\n
\n
Secrets belong in appropriate environment or secret-management systems.\n
\n
Sensitive information must not be unnecessarily logged.\n
\n
---\n
\n
# Authentication and Authorization\n
\n
Authentication and authorization are separate concerns.\n
\n
Every protected operation must explicitly enforce authorization.\n
\n
Do not assume that because a user can access an endpoint they are authorized to access every resource handled by that endpoint.\n
\n
Prefer explicit permission models such as:\n
\n
* Roles\n
* Permissions\n
* Policies\n
* Voters\n
* Claims\n
\n
depending on the framework.\n
\n
Design authorization so it remains manageable as the application grows.\n
\n
---\n
\n
# Error Handling\n
\n
Failures are expected in production systems.\n
\n
Handle errors deliberately.\n
\n
Do not silently swallow exceptions.\n
\n
Failures should:\n
\n
* Be logged appropriately\n
* Produce understandable user-facing messages\n
* Preserve diagnostic information for developers\n
* Avoid leaking sensitive technical details\n
\n
External systems must be treated as unreliable.\n
\n
Consider:\n
\n
* Timeouts\n
* Retries\n
* Exponential backoff\n
* Circuit breakers\n
* Partial failures\n
* Duplicate responses\n
* Unavailable services\n
\n
Never allow one unreliable external integration to unnecessarily destabilize the entire application.\n
\n
---\n
\n
# Logging and Observability\n
\n
Production software must be observable.\n
\n
Important operations should generate structured logs.\n
\n
Logs should contain enough context to investigate failures, including where appropriate:\n
\n
* Request ID\n
* Correlation ID\n
* User ID\n
* Job ID\n
* Entity ID\n
* Operation\n
* Duration\n
\n
Do not log secrets or sensitive personal information unnecessarily.\n
\n
Long-running operations should expose meaningful progress or status where appropriate.\n
\n
Important systems should be designed to support:\n
\n
* Metrics\n
* Monitoring\n
* Health checks\n
* Distributed tracing\n
* Alerting\n
\n
---\n
\n
# Background Jobs\n
\n
Background jobs must be assumed to run concurrently.\n
\n
Jobs should preferably be:\n
\n
* Idempotent\n
* Retryable\n
* Observable\n
* Independently executable\n
\n
Do not assume a job runs exactly once.\n
\n
Prevent duplicate processing where necessary.\n
\n
Failed jobs must not disappear silently.\n
\n
Use dead-letter handling or equivalent mechanisms where appropriate.\n
\n
---\n
\n
# Code Quality\n
\n
Write code for the next developer, not only for the compiler.\n
\n
Code should be:\n
\n
* Readable\n
* Predictable\n
* Explicit\n
* Consistent\n
* Easy to test\n
* Easy to modify\n
\n
Prefer descriptive names over abbreviations.\n
\n
Functions and methods should have one clear responsibility.\n
\n
Avoid excessively large:\n
\n
* Classes\n
* Services\n
* Components\n
* Controllers\n
* Methods\n
\n
Extract concepts when they represent meaningful domain or architectural responsibilities.\n
\n
Do not create abstractions purely to reduce line count.\n
\n
Comments should explain **why**, not restate **what** the code already says.\n
\n
---\n
\n
# Type Safety\n
\n
Use the strongest practical type system supported by the language and framework.\n
\n
Avoid ambiguous structures when a defined type, DTO, value object, interface, enum, or schema would provide stronger guarantees.\n
\n
Do not pass unstructured arrays or generic objects through multiple application layers when a proper model should exist.\n
\n
Make invalid states difficult to represent.\n
\n
---\n
\n
# Testing\n
\n
Important business logic requires automated tests.\n
\n
Prefer a balanced combination of:\n
\n
* Unit tests\n
* Integration tests\n
* API tests\n
* End-to-end tests\n
\n
Do not test framework internals.\n
\n
Test application behavior.\n
\n
Always consider edge cases such as:\n
\n
* Empty data\n
* Invalid input\n
* Unauthorized access\n
* Duplicate requests\n
* Concurrent modifications\n
* External service failures\n
* Very large datasets\n
* Boundary values\n
\n
Bug fixes should include a regression test whenever practical.\n
\n
---\n
\n
# Frontend and UX\n
\n
The frontend must look and behave like a polished enterprise application.\n
\n
A feature is not complete merely because it technically works.\n
\n
Every workflow should feel intentional.\n
\n
Interfaces must be:\n
\n
* Consistent\n
* Clear\n
* Responsive\n
* Predictable\n
* Accessible\n
* Efficient\n
* Visually professional\n
\n
Reuse a consistent design system.\n
\n
Do not invent different interaction patterns for equivalent actions.\n
\n
Maintain consistent:\n
\n
* Typography\n
* Spacing\n
* Colors\n
* Border radii\n
* Buttons\n
* Forms\n
* Tables\n
* Modals\n
* Notifications\n
* Icons\n
* Navigation\n
\n
The application should visually appear to come from one professional product team.\n
\n
---\n
\n
# User Flows\n
\n
Always think through the complete user journey.\n
\n
For every feature ask:\n
\n
* How does the user discover this feature?\n
* What is the most obvious next action?\n
* What happens while data loads?\n
* What happens when no data exists?\n
* What happens when an error occurs?\n
* What happens when the operation succeeds?\n
* Can the user accidentally execute the action twice?\n
* Can the user recover from a mistake?\n
* Is confirmation required for destructive actions?\n
* Is the workflow still usable with hundreds or thousands of records?\n
\n
Never leave users on ambiguous screens.\n
\n
Every operation should provide appropriate feedback.\n
\n
---\n
\n
# UI States\n
\n
Every data-driven component should consider at least:\n
\n
* Loading state\n
* Empty state\n
* Success state\n
* Error state\n
* Permission-denied state\n
\n
Buttons performing asynchronous operations should indicate progress and prevent accidental duplicate execution where necessary.\n
\n
Long operations must never make the application appear frozen.\n
\n
---\n
\n
# Forms\n
\n
Forms must provide clear validation.\n
\n
Whenever practical, validation feedback should appear close to the affected field.\n
\n
Preserve user input after validation failures.\n
\n
Clearly distinguish between:\n
\n
* Required fields\n
* Optional fields\n
* Invalid values\n
* Disabled fields\n
* Read-only information\n
\n
Destructive actions must be visually and behaviorally distinct from ordinary actions.\n
\n
---\n
\n
# Tables and Large Data Sets\n
\n
Enterprise applications frequently contain large tables.\n
\n
Tables should support appropriate combinations of:\n
\n
* Pagination\n
* Search\n
* Filtering\n
* Sorting\n
* Column configuration\n
* Bulk actions\n
\n
Never assume users only have a few records.\n
\n
Avoid rendering thousands of DOM elements unnecessarily.\n
\n
Use server-side processing or virtualization where appropriate.\n
\n
---\n
\n
# Accessibility\n
\n
Follow established accessibility standards such as WCAG where practical.\n
\n
Interfaces must remain usable with:\n
\n
* Keyboard navigation\n
* Screen readers\n
* Different screen sizes\n
* Browser zoom\n
* High-content-density scenarios\n
\n
Do not communicate important states exclusively through color.\n
\n
---\n
\n
# Responsive Design\n
\n
Interfaces must behave correctly across supported screen sizes.\n
\n
Desktop enterprise workflows may be optimized for desktop usage, but layouts must degrade gracefully on smaller screens.\n
\n
Avoid arbitrary fixed dimensions where responsive layout techniques are more appropriate.\n
\n
---\n
\n
# Consistency Over Cleverness\n
\n
Prefer established patterns over clever solutions.\n
\n
A developer familiar with the ecosystem should be able to understand the architecture without reverse-engineering unconventional patterns.\n
\n
Follow existing project conventions unless there is a strong reason to improve them.\n
\n
When changing an established convention, apply the change consistently rather than creating two competing approaches.\n
\n
---\n
\n
# Dependencies\n
\n
Before adding a dependency, evaluate:\n
\n
* Is it actively maintained?\n
* Is it widely used?\n
* Does it have known security problems?\n
* Is the functionality significant enough to justify another dependency?\n
* Could the framework already provide the same functionality?\n
\n
Avoid unnecessary dependencies.\n
\n
Do not reimplement mature security-critical functionality yourself.\n
\n
---\n
\n
# Compatibility and Change Management\n
\n
Treat existing production behavior as a contract.\n
\n
Before modifying an existing feature, consider:\n
\n
* Existing clients\n
* Existing API consumers\n
* Existing database records\n
* Existing integrations\n
* Existing user workflows\n
\n
Prefer backwards-compatible changes.\n
\n
If a breaking change is unavoidable, make it explicit and provide a migration path.\n
\n
---\n
\n
# Definition of Done\n
\n
A task is not complete simply because the happy path works.\n
\n
Before considering work finished, verify:\n
\n
1. Architecture is consistent with the existing system.\n
2. Code follows framework and language best practices.\n
3. Authorization is enforced.\n
4. Input is validated.\n
5. Error scenarios are handled.\n
6. Database access is efficient.\n
7. Concurrent execution is safe where relevant.\n
8. Large datasets have been considered.\n
9. The implementation can operate across multiple application instances.\n
10. Logs provide enough information for troubleshooting.\n
11. Relevant automated tests exist.\n
12. Loading, empty, error, and success states exist in the UI where applicable.\n
13. The user flow is intuitive.\n
14. The result visually matches the rest of the application.\n
15. No secrets or sensitive data are exposed.\n
16. Existing functionality and API contracts remain intact.\n
17. The solution would still be reasonable if usage increased by an order of magnitude.\n
\n
---\n
\n
# Decision Rule\n
\n
Whenever multiple implementations are possible, prefer the solution that would be expected from an experienced engineering team maintaining a long-lived enterprise product.\n
\n
Do not ask:\n
\n
> "What is the fastest way to make this work?"\n
\n
Ask:\n
\n
> "What solution would we be comfortable operating, debugging, extending, and securing in production for the next five years with thousands of concurrent users?"\n
\n
The final result must not feel like a prototype, proof of concept, generated demo, or internal tool unless explicitly requested.\n
\n
It should feel like a mature enterprise product built by an experienced professional software engineering team.\n
\n
\n
## Testing requirements\n
\n
\n
\n
## Security rules\n
\n
\n
\n
## Before finishing\n
\n
1. Run the tests.\n
2. Run static analysis.\n
3. Do not modify unrelated code.\n
4. Summarize the changes.\n
5. Report the tests you executed.\n
6. Report potential risks.\n
"""
-agentsMarkdownSnapshot: """
# Hirely — AGENTS.md\n
\n
Instructions for coding agents working in this project.\n
\n
## General Instructions\n
\n
_No project-specific instructions._\n
\n
## Architecture\n
\n
# Enterprise Application Architecture Rules\n
\n
The application is a production-grade enterprise system designed for thousands of concurrent users.\n
\n
The preferred technology stack is:\n
\n
* **Symfony** as the backend and authoritative application layer\n
* **React with TypeScript** as the frontend\n
* **Mercure** for real-time updates\n
* **Symfony Messenger** for asynchronous and background processing\n
* A relational database as the authoritative persistent data store\n
* Redis or another distributed cache only where it provides a clear architectural benefit\n
\n
The architecture must support horizontal scaling, multiple application instances, concurrent users, background workers, and real-time collaboration.\n
\n
The system must never be designed like a prototype or single-user application.\n
\n
---\n
\n
# High-Level Architecture\n
\n
Use the following logical architecture:\n
\n
```text\n
┌─────────────────────────────────────┐\n
│ React UI │\n
│ │\n
│ Components / Pages / Features │\n
│ Query Cache / Client State │\n
└─────────────────┬───────────────────┘\n
│\n
│ HTTPS / REST\n
▼\n
┌─────────────────────────────────────┐\n
│ Symfony │\n
│ │\n
│ Controllers / API │\n
│ ↓ │\n
│ Application Services / Use Cases │\n
│ ↓ │\n
│ Domain Logic │\n
│ ↓ │\n
│ Repositories / Infrastructure │\n
└───────────────┬───────┬─────────────┘\n
│ │\n
│ │\n
┌───────▼───┐ └───────────────┐\n
│ Database │ │\n
└───────────┘ │\n
▼\n
┌─────────────────┐\n
│ Symfony Messenger│\n
│ Background Jobs │\n
└─────────────────┘\n
\n
Symfony\n
│\n
│ Publish domain/application events\n
▼\n
┌──────────────┐\n
│ Mercure │\n
└──────┬───────┘\n
│ SSE\n
▼\n
┌──────────────┐\n
│ React Clients│\n
└──────────────┘\n
```\n
\n
Symfony is the **source of truth for all business logic**.\n
\n
React must never contain authoritative business rules that can affect data integrity or permissions.\n
\n
Mercure is responsible for notifying connected clients about changes.\n
\n
The database remains the authoritative source of persisted state.\n
\n
---\n
\n
# Backend Authority\n
\n
Symfony is responsible for:\n
\n
* Authentication\n
* Authorization\n
* Business rules\n
* Validation\n
* Transactions\n
* Persistence\n
* Integrations\n
* Background processing\n
* Audit logging\n
* Event publication\n
* API contracts\n
\n
React is responsible for:\n
\n
* Presentation\n
* Interaction\n
* Local UI state\n
* User workflows\n
* Displaying backend state\n
* Reacting to real-time notifications\n
\n
Never trust the frontend.\n
\n
Every operation must be validated and authorized again on the Symfony backend.\n
\n
---\n
\n
# Symfony Architecture\n
\n
Prefer a layered architecture.\n
\n
Recommended structure:\n
\n
```text\n
src/\n
├── Controller/\n
├── Application/\n
│ ├── Command/\n
│ ├── Query/\n
│ ├── DTO/\n
│ └── Service/\n
├── Domain/\n
│ ├── Entity/\n
│ ├── Event/\n
│ ├── Exception/\n
│ ├── Repository/\n
│ ├── Service/\n
│ └── ValueObject/\n
├── Infrastructure/\n
│ ├── Persistence/\n
│ ├── Messaging/\n
│ ├── Mercure/\n
│ ├── ExternalApi/\n
│ └── Storage/\n
├── Security/\n
└── Shared/\n
```\n
\n
This structure may be adapted to the size of the project, but responsibilities must remain clearly separated.\n
\n
Do not place substantial business logic inside controllers.\n
\n
A controller should typically:\n
\n
1. Receive the request.\n
2. Deserialize and validate input.\n
3. Check authorization.\n
4. Call an application service or use case.\n
5. Return a standardized response.\n
\n
---\n
\n
# Feature-Oriented Design\n
\n
For larger systems, prefer organizing business functionality around domains or features rather than creating huge global service directories.\n
\n
Example:\n
\n
```text\n
src/\n
├── User/\n
├── Project/\n
├── Task/\n
├── Notification/\n
├── Applicant/\n
└── Reporting/\n
```\n
\n
Each module may contain its own:\n
\n
```text\n
Application/\n
Domain/\n
Infrastructure/\n
```\n
\n
Avoid a monolithic `Service` directory containing hundreds of unrelated classes.\n
\n
---\n
\n
# API-First Architecture\n
\n
React communicates with Symfony through explicitly defined APIs.\n
\n
Do not directly couple frontend implementation details to database entities.\n
\n
Use:\n
\n
* Request DTOs\n
* Response DTOs\n
* API resources\n
* Explicit schemas\n
\n
Do not automatically expose Doctrine entities as public API contracts.\n
\n
Database entities and API representations serve different purposes and must be allowed to evolve independently.\n
\n
---\n
\n
# REST API\n
\n
REST is the preferred default communication mechanism.\n
\n
Use predictable resource-oriented endpoints.\n
\n
Examples:\n
\n
```text\n
GET /api/projects\n
GET /api/projects/{id}\n
POST /api/projects\n
PATCH /api/projects/{id}\n
DELETE /api/projects/{id}\n
```\n
\n
Complex commands may use explicit action endpoints when they represent real business operations.\n
\n
Example:\n
\n
```text\n
POST /api/projects/{id}/archive\n
POST /api/applicants/{id}/reject\n
POST /api/tasks/{id}/assign\n
```\n
\n
Do not distort the business model purely to force everything into CRUD semantics.\n
\n
---\n
\n
# API Versioning\n
\n
Public or externally consumed APIs must support controlled evolution.\n
\n
Breaking API changes must not silently affect existing clients.\n
\n
Use explicit versioning where necessary.\n
\n
Example:\n
\n
```text\n
/api/v1/...\n
```\n
\n
Internal APIs may avoid unnecessary versioning when frontend and backend are deployed together, but API contracts must still remain intentional and documented.\n
\n
---\n
\n
# Standard API Responses\n
\n
Keep responses consistent.\n
\n
For resources:\n
\n
```json\n
{\n
"data": {}\n
}\n
```\n
\n
For collections:\n
\n
```json\n
{\n
"data": [],\n
"meta": {\n
"page": 1,\n
"pageSize": 50,\n
"total": 1250\n
}\n
}\n
```\n
\n
For errors:\n
\n
```json\n
{\n
"error": {\n
"code": "PROJECT_NOT_FOUND",\n
"message": "Project could not be found."\n
}\n
}\n
```\n
\n
Validation errors should provide field-level information.\n
\n
---\n
\n
# React Architecture\n
\n
React should be written in TypeScript.\n
\n
Prefer a feature-based structure.\n
\n
Example:\n
\n
```text\n
src/\n
├── app/\n
├── features/\n
│ ├── projects/\n
│ ├── applicants/\n
│ ├── users/\n
│ └── notifications/\n
├── components/\n
├── hooks/\n
├── api/\n
├── auth/\n
├── realtime/\n
├── routing/\n
├── types/\n
└── utils/\n
```\n
\n
Keep feature-specific components within the feature whenever possible.\n
\n
Do not create one giant global component directory containing every component in the application.\n
\n
---\n
\n
# React State\n
\n
Differentiate between:\n
\n
### Server State\n
\n
Data originating from Symfony.\n
\n
Examples:\n
\n
* Users\n
* Projects\n
* Applicants\n
* Tasks\n
* Permissions\n
\n
Prefer a dedicated server-state solution such as:\n
\n
* TanStack Query\n
\n
Server state should not unnecessarily be duplicated into global frontend stores.\n
\n
### UI State\n
\n
Examples:\n
\n
* Modal open/closed\n
* Selected tab\n
* Temporary filter\n
* Sidebar state\n
\n
Keep UI state local whenever possible.\n
\n
### Global Client State\n
\n
Use global state management only where genuinely necessary.\n
\n
Do not create a global store merely because state management exists.\n
\n
---\n
\n
# Real-Time Architecture with Mercure\n
\n
Mercure is the preferred mechanism for real-time updates.\n
\n
Its purpose is to ensure that users see changes made by other users or backend processes without manually refreshing the page.\n
\n
Examples:\n
\n
* User A changes a project.\n
* User B currently has the same project open.\n
* User B should see the updated information automatically.\n
\n
Or:\n
\n
* A background worker completes an import.\n
* Connected users should see the new status immediately.\n
\n
Or:\n
\n
* Another employee creates a new applicant.\n
* Relevant applicant lists should update automatically.\n
\n
---\n
\n
# Mercure Is Not the Source of Truth\n
\n
This rule is critical:\n
\n
**Mercure transports change notifications. It is not the authoritative state store.**\n
\n
Symfony and the database remain authoritative.\n
\n
A Mercure message should typically tell the frontend:\n
\n
> Something changed.\n
\n
The frontend can then either:\n
\n
1. Apply a reliable payload directly.\n
\n
or preferably:\n
\n
2. Invalidate and refetch the affected server state.\n
\n
Example:\n
\n
```text\n
Symfony\n
↓\n
Database transaction\n
↓\n
Successful commit\n
↓\n
Mercure event\n
↓\n
React receives event\n
↓\n
TanStack Query invalidates affected query\n
↓\n
React fetches current authoritative state\n
```\n
\n
This avoids frontend state becoming inconsistent.\n
\n
---\n
\n
# Mercure Event Flow\n
\n
Preferred flow for a write operation:\n
\n
```text\n
React\n
│\n
│ PATCH /api/projects/123\n
▼\n
Symfony\n
│\n
├── Authorization\n
├── Validation\n
├── Business Logic\n
├── Database Transaction\n
└── Commit\n
│\n
▼\n
Application / Domain Event\n
│\n
▼\n
Mercure Publication\n
│\n
▼\n
Connected React Clients\n
│\n
▼\n
Query Invalidation / State Refresh\n
```\n
\n
Never publish the final change event before the database transaction has successfully completed.\n
\n
Users must never receive notifications for transactions that were rolled back.\n
\n
---\n
\n
# Mercure Topics\n
\n
Topics must be deliberate and predictable.\n
\n
Examples:\n
\n
```text\n
/project/123\n
/project/123/tasks\n
/applicants\n
/applicant/456\n
/user/123/notifications\n
/organization/42/projects\n
```\n
\n
Avoid placing every event into one global topic.\n
\n
Users should only subscribe to information relevant to the current screen or workflow.\n
\n
---\n
\n
# Mercure Security\n
\n
Private information must use private Mercure updates.\n
\n
Do not expose internal events through publicly readable topics.\n
\n
Subscription authorization must respect the same permission model as the backend.\n
\n
A user who cannot access an entity through the REST API must not receive its data through Mercure.\n
\n
Never rely on frontend filtering for Mercure security.\n
\n
---\n
\n
# Mercure Event Payloads\n
\n
Events should have predictable structures.\n
\n
Example:\n
\n
```json\n
{\n
"event": "project.updated",\n
"entity": "project",\n
"id": "123",\n
"version": 7,\n
"timestamp": "2026-09-20T15:30:00Z"\n
}\n
```\n
\n
Avoid unnecessarily sending complete entities through every event.\n
\n
Prefer small event payloads when the frontend can refetch authoritative data.\n
\n
Large entities should not continuously be broadcast to many clients.\n
\n
---\n
\n
# Event Types\n
\n
Use meaningful event names.\n
\n
Examples:\n
\n
```text\n
project.created\n
project.updated\n
project.deleted\n
\n
applicant.created\n
applicant.updated\n
applicant.deleted\n
\n
task.assigned\n
task.completed\n
\n
import.started\n
import.progress\n
import.completed\n
import.failed\n
```\n
\n
Do not use vague events such as:\n
\n
```text\n
update\n
changed\n
event\n
message\n
```\n
\n
Events should make their purpose immediately understandable.\n
\n
---\n
\n
# Reconnection and Lost Events\n
\n
Real-time applications must assume connections can be interrupted.\n
\n
Possible causes include:\n
\n
* Laptop sleep\n
* Network interruption\n
* Reverse proxy restart\n
* Browser suspension\n
* Mobile network changes\n
* Mercure restart\n
\n
The application must recover automatically.\n
\n
React must never assume that receiving every Mercure event is guaranteed.\n
\n
After reconnecting, the application should synchronize relevant state again with Symfony.\n
\n
The authoritative REST API must always be capable of reconstructing the correct UI state.\n
\n
---\n
\n
# Multiple Browser Tabs and Clients\n
\n
Assume users may have:\n
\n
* Multiple browser tabs\n
* Multiple browser windows\n
* Multiple devices\n
\n
Changes from one session should propagate to other sessions where relevant.\n
\n
Do not rely exclusively on local frontend state.\n
\n
---\n
\n
# Optimistic Updates\n
\n
Optimistic UI updates may be used where they significantly improve usability.\n
\n
However:\n
\n
1. Symfony remains authoritative.\n
2. The optimistic update must be reversible.\n
3. Failed requests must restore previous state.\n
4. Incoming Mercure events must not corrupt optimistic state.\n
5. Conflict scenarios must be handled.\n
\n
## Coding Standards\n
\n
# Enterprise Software Engineering Rules\n
\n
You are developing production-grade enterprise software.\n
\n
Every architectural decision, implementation, UI component, API, database query, background process, and integration must be designed with the assumption that this application may be used by **several thousand concurrent users**.\n
\n
The goal is not merely to make features work. The goal is to build software that feels and behaves like a mature, professionally engineered enterprise product.\n
\n
## Core Engineering Principles\n
\n
Always optimize for:\n
\n
* Maintainability\n
* Scalability\n
* Reliability\n
* Security\n
* Performance\n
* Observability\n
* Testability\n
* Extensibility\n
* Clear architecture\n
* Excellent user experience\n
\n
Never implement a quick workaround when a clean and maintainable solution is reasonably possible.\n
\n
Avoid technical debt unless there is an explicit and documented reason for it.\n
\n
Follow established industry standards, framework conventions, proven architectural patterns, and language-specific best practices.\n
\n
Do not invent custom solutions when a well-established standard or framework mechanism already exists.\n
\n
At the same time, avoid unnecessary abstraction and overengineering. Complexity must solve an actual or foreseeable problem.\n
\n
---\n
\n
# Architecture\n
\n
Keep responsibilities clearly separated.\n
\n
Prefer clear architectural boundaries such as:\n
\n
* Presentation / UI\n
* Application / Use Cases\n
* Domain / Business Logic\n
* Infrastructure\n
* Persistence\n
* External integrations\n
\n
Business logic must not be hidden inside controllers, UI components, database queries, templates, or infrastructure code.\n
\n
Controllers and API endpoints should primarily:\n
\n
1. Validate and authorize the request.\n
2. Delegate work to the appropriate application/service layer.\n
3. Return a well-defined response.\n
\n
Design modules with high cohesion and low coupling.\n
\n
Dependencies should point toward stable abstractions.\n
\n
Do not create circular dependencies.\n
\n
Prefer dependency injection over hidden global state.\n
\n
---\n
\n
# Scalability\n
\n
Always assume the system may eventually process:\n
\n
* Thousands of concurrent users\n
* Large database tables\n
* Millions of records\n
* High API request volumes\n
* Multiple application instances\n
* Multiple workers\n
* Concurrent background jobs\n
\n
Never rely on application-local memory for shared state unless explicitly appropriate.\n
\n
The application must be able to run horizontally across multiple instances.\n
\n
Avoid architecture that requires one specific server instance to process a request.\n
\n
Design operations to be safe under concurrency.\n
\n
Use appropriate:\n
\n
* Transactions\n
* Locking\n
* Optimistic concurrency\n
* Idempotency\n
* Queues\n
* Caching\n
* Pagination\n
* Batch processing\n
\n
where required.\n
\n
Do not load large datasets into memory unnecessarily.\n
\n
Never fetch an unlimited database result set.\n
\n
Every potentially large list must support pagination, cursor-based pagination, filtering, or another appropriate limiting strategy.\n
\n
---\n
\n
# Database\n
\n
Treat the database as a critical shared resource.\n
\n
Avoid:\n
\n
* N+1 queries\n
* Unindexed filtering\n
* Unindexed joins on large datasets\n
* Full table scans\n
* SELECT *\n
* Excessive query counts\n
* Database calls inside loops\n
* Large synchronous bulk operations\n
\n
Consider indexing whenever introducing:\n
\n
* Search fields\n
* Foreign keys\n
* Frequently filtered columns\n
* Frequently sorted columns\n
* High-volume joins\n
\n
Database constraints should enforce important data integrity rules whenever possible.\n
\n
Use transactions when an operation modifies multiple related pieces of data.\n
\n
Migrations must be safe for production environments.\n
\n
Consider the impact of schema changes on large tables and running application instances.\n
\n
Never assume the database is empty or small.\n
\n
---\n
\n
# Performance\n
\n
Performance must be considered during implementation, not added as an afterthought.\n
\n
Avoid premature micro-optimization, but identify obvious scalability bottlenecks before introducing them.\n
\n
Expensive work that does not need to happen synchronously should be handled asynchronously.\n
\n
Examples include:\n
\n
* Email\n
* File processing\n
* Large imports\n
* Large exports\n
* Image processing\n
* Report generation\n
* External synchronization\n
* Batch operations\n
\n
Use caching when it provides meaningful benefit, but always define a valid invalidation strategy.\n
\n
Never introduce caching without understanding when cached data becomes stale.\n
\n
---\n
\n
# APIs\n
\n
APIs must be predictable, consistent, secure, and versionable.\n
\n
Use established HTTP semantics and appropriate status codes.\n
\n
API responses should have consistent structures.\n
\n
Validation errors must be machine-readable.\n
\n
Errors must never expose:\n
\n
* Stack traces\n
* Credentials\n
* Internal infrastructure information\n
* Database internals\n
* Secrets\n
\n
Design APIs so clients can safely retry requests where appropriate.\n
\n
Use idempotency for operations where duplicate requests could cause unwanted side effects.\n
\n
Always consider backward compatibility before changing an existing API contract.\n
\n
Avoid breaking changes whenever possible.\n
\n
---\n
\n
# Security\n
\n
Security is mandatory and part of the architecture.\n
\n
Follow secure-by-default principles.\n
\n
Always validate untrusted input.\n
\n
Always implement authorization server-side.\n
\n
Never rely solely on frontend permission checks.\n
\n
Apply least-privilege principles.\n
\n
Protect against common vulnerabilities including:\n
\n
* SQL injection\n
* XSS\n
* CSRF\n
* SSRF\n
* Broken access control\n
* Insecure direct object references\n
* Command injection\n
* Path traversal\n
* Unsafe file uploads\n
* Mass assignment\n
* Sensitive information disclosure\n
\n
Never hardcode:\n
\n
* Passwords\n
* API keys\n
* Tokens\n
* Certificates\n
* Private keys\n
* Connection secrets\n
\n
Secrets belong in appropriate environment or secret-management systems.\n
\n
Sensitive information must not be unnecessarily logged.\n
\n
---\n
\n
# Authentication and Authorization\n
\n
Authentication and authorization are separate concerns.\n
\n
Every protected operation must explicitly enforce authorization.\n
\n
Do not assume that because a user can access an endpoint they are authorized to access every resource handled by that endpoint.\n
\n
Prefer explicit permission models such as:\n
\n
* Roles\n
* Permissions\n
* Policies\n
* Voters\n
* Claims\n
\n
depending on the framework.\n
\n
Design authorization so it remains manageable as the application grows.\n
\n
---\n
\n
# Error Handling\n
\n
Failures are expected in production systems.\n
\n
Handle errors deliberately.\n
\n
Do not silently swallow exceptions.\n
\n
Failures should:\n
\n
* Be logged appropriately\n
* Produce understandable user-facing messages\n
* Preserve diagnostic information for developers\n
* Avoid leaking sensitive technical details\n
\n
External systems must be treated as unreliable.\n
\n
Consider:\n
\n
* Timeouts\n
* Retries\n
* Exponential backoff\n
* Circuit breakers\n
* Partial failures\n
* Duplicate responses\n
* Unavailable services\n
\n
Never allow one unreliable external integration to unnecessarily destabilize the entire application.\n
\n
---\n
\n
# Logging and Observability\n
\n
Production software must be observable.\n
\n
Important operations should generate structured logs.\n
\n
Logs should contain enough context to investigate failures, including where appropriate:\n
\n
* Request ID\n
* Correlation ID\n
* User ID\n
* Job ID\n
* Entity ID\n
* Operation\n
* Duration\n
\n
Do not log secrets or sensitive personal information unnecessarily.\n
\n
Long-running operations should expose meaningful progress or status where appropriate.\n
\n
Important systems should be designed to support:\n
\n
* Metrics\n
* Monitoring\n
* Health checks\n
* Distributed tracing\n
* Alerting\n
\n
---\n
\n
# Background Jobs\n
\n
Background jobs must be assumed to run concurrently.\n
\n
Jobs should preferably be:\n
\n
* Idempotent\n
* Retryable\n
* Observable\n
* Independently executable\n
\n
Do not assume a job runs exactly once.\n
\n
Prevent duplicate processing where necessary.\n
\n
Failed jobs must not disappear silently.\n
\n
Use dead-letter handling or equivalent mechanisms where appropriate.\n
\n
---\n
\n
# Code Quality\n
\n
Write code for the next developer, not only for the compiler.\n
\n
Code should be:\n
\n
* Readable\n
* Predictable\n
* Explicit\n
* Consistent\n
* Easy to test\n
* Easy to modify\n
\n
Prefer descriptive names over abbreviations.\n
\n
Functions and methods should have one clear responsibility.\n
\n
Avoid excessively large:\n
\n
* Classes\n
* Services\n
* Components\n
* Controllers\n
* Methods\n
\n
Extract concepts when they represent meaningful domain or architectural responsibilities.\n
\n
Do not create abstractions purely to reduce line count.\n
\n
Comments should explain **why**, not restate **what** the code already says.\n
\n
---\n
\n
# Type Safety\n
\n
Use the strongest practical type system supported by the language and framework.\n
\n
Avoid ambiguous structures when a defined type, DTO, value object, interface, enum, or schema would provide stronger guarantees.\n
\n
Do not pass unstructured arrays or generic objects through multiple application layers when a proper model should exist.\n
\n
Make invalid states difficult to represent.\n
\n
---\n
\n
# Testing\n
\n
Important business logic requires automated tests.\n
\n
Prefer a balanced combination of:\n
\n
* Unit tests\n
* Integration tests\n
* API tests\n
* End-to-end tests\n
\n
Do not test framework internals.\n
\n
Test application behavior.\n
\n
Always consider edge cases such as:\n
\n
* Empty data\n
* Invalid input\n
* Unauthorized access\n
* Duplicate requests\n
* Concurrent modifications\n
* External service failures\n
* Very large datasets\n
* Boundary values\n
\n
Bug fixes should include a regression test whenever practical.\n
\n
---\n
\n
# Frontend and UX\n
\n
The frontend must look and behave like a polished enterprise application.\n
\n
A feature is not complete merely because it technically works.\n
\n
Every workflow should feel intentional.\n
\n
Interfaces must be:\n
\n
* Consistent\n
* Clear\n
* Responsive\n
* Predictable\n
* Accessible\n
* Efficient\n
* Visually professional\n
\n
Reuse a consistent design system.\n
\n
Do not invent different interaction patterns for equivalent actions.\n
\n
Maintain consistent:\n
\n
* Typography\n
* Spacing\n
* Colors\n
* Border radii\n
* Buttons\n
* Forms\n
* Tables\n
* Modals\n
* Notifications\n
* Icons\n
* Navigation\n
\n
The application should visually appear to come from one professional product team.\n
\n
---\n
\n
# User Flows\n
\n
Always think through the complete user journey.\n
\n
For every feature ask:\n
\n
* How does the user discover this feature?\n
* What is the most obvious next action?\n
* What happens while data loads?\n
* What happens when no data exists?\n
* What happens when an error occurs?\n
* What happens when the operation succeeds?\n
* Can the user accidentally execute the action twice?\n
* Can the user recover from a mistake?\n
* Is confirmation required for destructive actions?\n
* Is the workflow still usable with hundreds or thousands of records?\n
\n
Never leave users on ambiguous screens.\n
\n
Every operation should provide appropriate feedback.\n
\n
---\n
\n
# UI States\n
\n
Every data-driven component should consider at least:\n
\n
* Loading state\n
* Empty state\n
* Success state\n
* Error state\n
* Permission-denied state\n
\n
Buttons performing asynchronous operations should indicate progress and prevent accidental duplicate execution where necessary.\n
\n
Long operations must never make the application appear frozen.\n
\n
---\n
\n
# Forms\n
\n
Forms must provide clear validation.\n
\n
Whenever practical, validation feedback should appear close to the affected field.\n
\n
Preserve user input after validation failures.\n
\n
Clearly distinguish between:\n
\n
* Required fields\n
* Optional fields\n
* Invalid values\n
* Disabled fields\n
* Read-only information\n
\n
Destructive actions must be visually and behaviorally distinct from ordinary actions.\n
\n
---\n
\n
# Tables and Large Data Sets\n
\n
Enterprise applications frequently contain large tables.\n
\n
Tables should support appropriate combinations of:\n
\n
* Pagination\n
* Search\n
* Filtering\n
* Sorting\n
* Column configuration\n
* Bulk actions\n
\n
Never assume users only have a few records.\n
\n
Avoid rendering thousands of DOM elements unnecessarily.\n
\n
Use server-side processing or virtualization where appropriate.\n
\n
---\n
\n
# Accessibility\n
\n
Follow established accessibility standards such as WCAG where practical.\n
\n
Interfaces must remain usable with:\n
\n
* Keyboard navigation\n
* Screen readers\n
* Different screen sizes\n
* Browser zoom\n
* High-content-density scenarios\n
\n
Do not communicate important states exclusively through color.\n
\n
---\n
\n
# Responsive Design\n
\n
Interfaces must behave correctly across supported screen sizes.\n
\n
Desktop enterprise workflows may be optimized for desktop usage, but layouts must degrade gracefully on smaller screens.\n
\n
Avoid arbitrary fixed dimensions where responsive layout techniques are more appropriate.\n
\n
---\n
\n
# Consistency Over Cleverness\n
\n
Prefer established patterns over clever solutions.\n
\n
A developer familiar with the ecosystem should be able to understand the architecture without reverse-engineering unconventional patterns.\n
\n
Follow existing project conventions unless there is a strong reason to improve them.\n
\n
When changing an established convention, apply the change consistently rather than creating two competing approaches.\n
\n
---\n
\n
# Dependencies\n
\n
Before adding a dependency, evaluate:\n
\n
* Is it actively maintained?\n
* Is it widely used?\n
* Does it have known security problems?\n
* Is the functionality significant enough to justify another dependency?\n
* Could the framework already provide the same functionality?\n
\n
Avoid unnecessary dependencies.\n
\n
Do not reimplement mature security-critical functionality yourself.\n
\n
---\n
\n
# Compatibility and Change Management\n
\n
Treat existing production behavior as a contract.\n
\n
Before modifying an existing feature, consider:\n
\n
* Existing clients\n
* Existing API consumers\n
* Existing database records\n
* Existing integrations\n
* Existing user workflows\n
\n
Prefer backwards-compatible changes.\n
\n
If a breaking change is unavoidable, make it explicit and provide a migration path.\n
\n
---\n
\n
# Definition of Done\n
\n
A task is not complete simply because the happy path works.\n
\n
Before considering work finished, verify:\n
\n
1. Architecture is consistent with the existing system.\n
2. Code follows framework and language best practices.\n
3. Authorization is enforced.\n
4. Input is validated.\n
5. Error scenarios are handled.\n
6. Database access is efficient.\n
7. Concurrent execution is safe where relevant.\n
8. Large datasets have been considered.\n
9. The implementation can operate across multiple application instances.\n
10. Logs provide enough information for troubleshooting.\n
11. Relevant automated tests exist.\n
12. Loading, empty, error, and success states exist in the UI where applicable.\n
13. The user flow is intuitive.\n
14. The result visually matches the rest of the application.\n
15. No secrets or sensitive data are exposed.\n
16. Existing functionality and API contracts remain intact.\n
17. The solution would still be reasonable if usage increased by an order of magnitude.\n
\n
---\n
\n
# Decision Rule\n
\n
Whenever multiple implementations are possible, prefer the solution that would be expected from an experienced engineering team maintaining a long-lived enterprise product.\n
\n
Do not ask:\n
\n
> "What is the fastest way to make this work?"\n
\n
Ask:\n
\n
> "What solution would we be comfortable operating, debugging, extending, and securing in production for the next five years with thousands of concurrent users?"\n
\n
The final result must not feel like a prototype, proof of concept, generated demo, or internal tool unless explicitly requested.\n
\n
It should feel like a mature enterprise product built by an experienced professional software engineering team.\n
\n
## Testing Rules\n
\n
_No project-specific instructions._\n
\n
## Git Rules\n
\n
_No project-specific instructions._\n
\n
## Security Rules\n
\n
_No project-specific instructions._\n
\n
## Documentation\n
\n
_No project-specific instructions._\n
"""
-claudeMarkdownSnapshot: """
# Hirely — CLAUDE.md\n
\n
Instructions for Claude Code working in this project.\n
\n
## General Instructions\n
\n
_No project-specific instructions._\n
\n
## Architecture\n
\n
# Enterprise Application Architecture Rules\n
\n
The application is a production-grade enterprise system designed for thousands of concurrent users.\n
\n
The preferred technology stack is:\n
\n
* **Symfony** as the backend and authoritative application layer\n
* **React with TypeScript** as the frontend\n
* **Mercure** for real-time updates\n
* **Symfony Messenger** for asynchronous and background processing\n
* A relational database as the authoritative persistent data store\n
* Redis or another distributed cache only where it provides a clear architectural benefit\n
\n
The architecture must support horizontal scaling, multiple application instances, concurrent users, background workers, and real-time collaboration.\n
\n
The system must never be designed like a prototype or single-user application.\n
\n
---\n
\n
# High-Level Architecture\n
\n
Use the following logical architecture:\n
\n
```text\n
┌─────────────────────────────────────┐\n
│ React UI │\n
│ │\n
│ Components / Pages / Features │\n
│ Query Cache / Client State │\n
└─────────────────┬───────────────────┘\n
│\n
│ HTTPS / REST\n
▼\n
┌─────────────────────────────────────┐\n
│ Symfony │\n
│ │\n
│ Controllers / API │\n
│ ↓ │\n
│ Application Services / Use Cases │\n
│ ↓ │\n
│ Domain Logic │\n
│ ↓ │\n
│ Repositories / Infrastructure │\n
└───────────────┬───────┬─────────────┘\n
│ │\n
│ │\n
┌───────▼───┐ └───────────────┐\n
│ Database │ │\n
└───────────┘ │\n
▼\n
┌─────────────────┐\n
│ Symfony Messenger│\n
│ Background Jobs │\n
└─────────────────┘\n
\n
Symfony\n
│\n
│ Publish domain/application events\n
▼\n
┌──────────────┐\n
│ Mercure │\n
└──────┬───────┘\n
│ SSE\n
▼\n
┌──────────────┐\n
│ React Clients│\n
└──────────────┘\n
```\n
\n
Symfony is the **source of truth for all business logic**.\n
\n
React must never contain authoritative business rules that can affect data integrity or permissions.\n
\n
Mercure is responsible for notifying connected clients about changes.\n
\n
The database remains the authoritative source of persisted state.\n
\n
---\n
\n
# Backend Authority\n
\n
Symfony is responsible for:\n
\n
* Authentication\n
* Authorization\n
* Business rules\n
* Validation\n
* Transactions\n
* Persistence\n
* Integrations\n
* Background processing\n
* Audit logging\n
* Event publication\n
* API contracts\n
\n
React is responsible for:\n
\n
* Presentation\n
* Interaction\n
* Local UI state\n
* User workflows\n
* Displaying backend state\n
* Reacting to real-time notifications\n
\n
Never trust the frontend.\n
\n
Every operation must be validated and authorized again on the Symfony backend.\n
\n
---\n
\n
# Symfony Architecture\n
\n
Prefer a layered architecture.\n
\n
Recommended structure:\n
\n
```text\n
src/\n
├── Controller/\n
├── Application/\n
│ ├── Command/\n
│ ├── Query/\n
│ ├── DTO/\n
│ └── Service/\n
├── Domain/\n
│ ├── Entity/\n
│ ├── Event/\n
│ ├── Exception/\n
│ ├── Repository/\n
│ ├── Service/\n
│ └── ValueObject/\n
├── Infrastructure/\n
│ ├── Persistence/\n
│ ├── Messaging/\n
│ ├── Mercure/\n
│ ├── ExternalApi/\n
│ └── Storage/\n
├── Security/\n
└── Shared/\n
```\n
\n
This structure may be adapted to the size of the project, but responsibilities must remain clearly separated.\n
\n
Do not place substantial business logic inside controllers.\n
\n
A controller should typically:\n
\n
1. Receive the request.\n
2. Deserialize and validate input.\n
3. Check authorization.\n
4. Call an application service or use case.\n
5. Return a standardized response.\n
\n
---\n
\n
# Feature-Oriented Design\n
\n
For larger systems, prefer organizing business functionality around domains or features rather than creating huge global service directories.\n
\n
Example:\n
\n
```text\n
src/\n
├── User/\n
├── Project/\n
├── Task/\n
├── Notification/\n
├── Applicant/\n
└── Reporting/\n
```\n
\n
Each module may contain its own:\n
\n
```text\n
Application/\n
Domain/\n
Infrastructure/\n
```\n
\n
Avoid a monolithic `Service` directory containing hundreds of unrelated classes.\n
\n
---\n
\n
# API-First Architecture\n
\n
React communicates with Symfony through explicitly defined APIs.\n
\n
Do not directly couple frontend implementation details to database entities.\n
\n
Use:\n
\n
* Request DTOs\n
* Response DTOs\n
* API resources\n
* Explicit schemas\n
\n
Do not automatically expose Doctrine entities as public API contracts.\n
\n
Database entities and API representations serve different purposes and must be allowed to evolve independently.\n
\n
---\n
\n
# REST API\n
\n
REST is the preferred default communication mechanism.\n
\n
Use predictable resource-oriented endpoints.\n
\n
Examples:\n
\n
```text\n
GET /api/projects\n
GET /api/projects/{id}\n
POST /api/projects\n
PATCH /api/projects/{id}\n
DELETE /api/projects/{id}\n
```\n
\n
Complex commands may use explicit action endpoints when they represent real business operations.\n
\n
Example:\n
\n
```text\n
POST /api/projects/{id}/archive\n
POST /api/applicants/{id}/reject\n
POST /api/tasks/{id}/assign\n
```\n
\n
Do not distort the business model purely to force everything into CRUD semantics.\n
\n
---\n
\n
# API Versioning\n
\n
Public or externally consumed APIs must support controlled evolution.\n
\n
Breaking API changes must not silently affect existing clients.\n
\n
Use explicit versioning where necessary.\n
\n
Example:\n
\n
```text\n
/api/v1/...\n
```\n
\n
Internal APIs may avoid unnecessary versioning when frontend and backend are deployed together, but API contracts must still remain intentional and documented.\n
\n
---\n
\n
# Standard API Responses\n
\n
Keep responses consistent.\n
\n
For resources:\n
\n
```json\n
{\n
"data": {}\n
}\n
```\n
\n
For collections:\n
\n
```json\n
{\n
"data": [],\n
"meta": {\n
"page": 1,\n
"pageSize": 50,\n
"total": 1250\n
}\n
}\n
```\n
\n
For errors:\n
\n
```json\n
{\n
"error": {\n
"code": "PROJECT_NOT_FOUND",\n
"message": "Project could not be found."\n
}\n
}\n
```\n
\n
Validation errors should provide field-level information.\n
\n
---\n
\n
# React Architecture\n
\n
React should be written in TypeScript.\n
\n
Prefer a feature-based structure.\n
\n
Example:\n
\n
```text\n
src/\n
├── app/\n
├── features/\n
│ ├── projects/\n
│ ├── applicants/\n
│ ├── users/\n
│ └── notifications/\n
├── components/\n
├── hooks/\n
├── api/\n
├── auth/\n
├── realtime/\n
├── routing/\n
├── types/\n
└── utils/\n
```\n
\n
Keep feature-specific components within the feature whenever possible.\n
\n
Do not create one giant global component directory containing every component in the application.\n
\n
---\n
\n
# React State\n
\n
Differentiate between:\n
\n
### Server State\n
\n
Data originating from Symfony.\n
\n
Examples:\n
\n
* Users\n
* Projects\n
* Applicants\n
* Tasks\n
* Permissions\n
\n
Prefer a dedicated server-state solution such as:\n
\n
* TanStack Query\n
\n
Server state should not unnecessarily be duplicated into global frontend stores.\n
\n
### UI State\n
\n
Examples:\n
\n
* Modal open/closed\n
* Selected tab\n
* Temporary filter\n
* Sidebar state\n
\n
Keep UI state local whenever possible.\n
\n
### Global Client State\n
\n
Use global state management only where genuinely necessary.\n
\n
Do not create a global store merely because state management exists.\n
\n
---\n
\n
# Real-Time Architecture with Mercure\n
\n
Mercure is the preferred mechanism for real-time updates.\n
\n
Its purpose is to ensure that users see changes made by other users or backend processes without manually refreshing the page.\n
\n
Examples:\n
\n
* User A changes a project.\n
* User B currently has the same project open.\n
* User B should see the updated information automatically.\n
\n
Or:\n
\n
* A background worker completes an import.\n
* Connected users should see the new status immediately.\n
\n
Or:\n
\n
* Another employee creates a new applicant.\n
* Relevant applicant lists should update automatically.\n
\n
---\n
\n
# Mercure Is Not the Source of Truth\n
\n
This rule is critical:\n
\n
**Mercure transports change notifications. It is not the authoritative state store.**\n
\n
Symfony and the database remain authoritative.\n
\n
A Mercure message should typically tell the frontend:\n
\n
> Something changed.\n
\n
The frontend can then either:\n
\n
1. Apply a reliable payload directly.\n
\n
or preferably:\n
\n
2. Invalidate and refetch the affected server state.\n
\n
Example:\n
\n
```text\n
Symfony\n
↓\n
Database transaction\n
↓\n
Successful commit\n
↓\n
Mercure event\n
↓\n
React receives event\n
↓\n
TanStack Query invalidates affected query\n
↓\n
React fetches current authoritative state\n
```\n
\n
This avoids frontend state becoming inconsistent.\n
\n
---\n
\n
# Mercure Event Flow\n
\n
Preferred flow for a write operation:\n
\n
```text\n
React\n
│\n
│ PATCH /api/projects/123\n
▼\n
Symfony\n
│\n
├── Authorization\n
├── Validation\n
├── Business Logic\n
├── Database Transaction\n
└── Commit\n
│\n
▼\n
Application / Domain Event\n
│\n
▼\n
Mercure Publication\n
│\n
▼\n
Connected React Clients\n
│\n
▼\n
Query Invalidation / State Refresh\n
```\n
\n
Never publish the final change event before the database transaction has successfully completed.\n
\n
Users must never receive notifications for transactions that were rolled back.\n
\n
---\n
\n
# Mercure Topics\n
\n
Topics must be deliberate and predictable.\n
\n
Examples:\n
\n
```text\n
/project/123\n
/project/123/tasks\n
/applicants\n
/applicant/456\n
/user/123/notifications\n
/organization/42/projects\n
```\n
\n
Avoid placing every event into one global topic.\n
\n
Users should only subscribe to information relevant to the current screen or workflow.\n
\n
---\n
\n
# Mercure Security\n
\n
Private information must use private Mercure updates.\n
\n
Do not expose internal events through publicly readable topics.\n
\n
Subscription authorization must respect the same permission model as the backend.\n
\n
A user who cannot access an entity through the REST API must not receive its data through Mercure.\n
\n
Never rely on frontend filtering for Mercure security.\n
\n
---\n
\n
# Mercure Event Payloads\n
\n
Events should have predictable structures.\n
\n
Example:\n
\n
```json\n
{\n
"event": "project.updated",\n
"entity": "project",\n
"id": "123",\n
"version": 7,\n
"timestamp": "2026-09-20T15:30:00Z"\n
}\n
```\n
\n
Avoid unnecessarily sending complete entities through every event.\n
\n
Prefer small event payloads when the frontend can refetch authoritative data.\n
\n
Large entities should not continuously be broadcast to many clients.\n
\n
---\n
\n
# Event Types\n
\n
Use meaningful event names.\n
\n
Examples:\n
\n
```text\n
project.created\n
project.updated\n
project.deleted\n
\n
applicant.created\n
applicant.updated\n
applicant.deleted\n
\n
task.assigned\n
task.completed\n
\n
import.started\n
import.progress\n
import.completed\n
import.failed\n
```\n
\n
Do not use vague events such as:\n
\n
```text\n
update\n
changed\n
event\n
message\n
```\n
\n
Events should make their purpose immediately understandable.\n
\n
---\n
\n
# Reconnection and Lost Events\n
\n
Real-time applications must assume connections can be interrupted.\n
\n
Possible causes include:\n
\n
* Laptop sleep\n
* Network interruption\n
* Reverse proxy restart\n
* Browser suspension\n
* Mobile network changes\n
* Mercure restart\n
\n
The application must recover automatically.\n
\n
React must never assume that receiving every Mercure event is guaranteed.\n
\n
After reconnecting, the application should synchronize relevant state again with Symfony.\n
\n
The authoritative REST API must always be capable of reconstructing the correct UI state.\n
\n
---\n
\n
# Multiple Browser Tabs and Clients\n
\n
Assume users may have:\n
\n
* Multiple browser tabs\n
* Multiple browser windows\n
* Multiple devices\n
\n
Changes from one session should propagate to other sessions where relevant.\n
\n
Do not rely exclusively on local frontend state.\n
\n
---\n
\n
# Optimistic Updates\n
\n
Optimistic UI updates may be used where they significantly improve usability.\n
\n
However:\n
\n
1. Symfony remains authoritative.\n
2. The optimistic update must be reversible.\n
3. Failed requests must restore previous state.\n
4. Incoming Mercure events must not corrupt optimistic state.\n
5. Conflict scenarios must be handled.\n
\n
## Coding Standards\n
\n
# Enterprise Software Engineering Rules\n
\n
You are developing production-grade enterprise software.\n
\n
Every architectural decision, implementation, UI component, API, database query, background process, and integration must be designed with the assumption that this application may be used by **several thousand concurrent users**.\n
\n
The goal is not merely to make features work. The goal is to build software that feels and behaves like a mature, professionally engineered enterprise product.\n
\n
## Core Engineering Principles\n
\n
Always optimize for:\n
\n
* Maintainability\n
* Scalability\n
* Reliability\n
* Security\n
* Performance\n
* Observability\n
* Testability\n
* Extensibility\n
* Clear architecture\n
* Excellent user experience\n
\n
Never implement a quick workaround when a clean and maintainable solution is reasonably possible.\n
\n
Avoid technical debt unless there is an explicit and documented reason for it.\n
\n
Follow established industry standards, framework conventions, proven architectural patterns, and language-specific best practices.\n
\n
Do not invent custom solutions when a well-established standard or framework mechanism already exists.\n
\n
At the same time, avoid unnecessary abstraction and overengineering. Complexity must solve an actual or foreseeable problem.\n
\n
---\n
\n
# Architecture\n
\n
Keep responsibilities clearly separated.\n
\n
Prefer clear architectural boundaries such as:\n
\n
* Presentation / UI\n
* Application / Use Cases\n
* Domain / Business Logic\n
* Infrastructure\n
* Persistence\n
* External integrations\n
\n
Business logic must not be hidden inside controllers, UI components, database queries, templates, or infrastructure code.\n
\n
Controllers and API endpoints should primarily:\n
\n
1. Validate and authorize the request.\n
2. Delegate work to the appropriate application/service layer.\n
3. Return a well-defined response.\n
\n
Design modules with high cohesion and low coupling.\n
\n
Dependencies should point toward stable abstractions.\n
\n
Do not create circular dependencies.\n
\n
Prefer dependency injection over hidden global state.\n
\n
---\n
\n
# Scalability\n
\n
Always assume the system may eventually process:\n
\n
* Thousands of concurrent users\n
* Large database tables\n
* Millions of records\n
* High API request volumes\n
* Multiple application instances\n
* Multiple workers\n
* Concurrent background jobs\n
\n
Never rely on application-local memory for shared state unless explicitly appropriate.\n
\n
The application must be able to run horizontally across multiple instances.\n
\n
Avoid architecture that requires one specific server instance to process a request.\n
\n
Design operations to be safe under concurrency.\n
\n
Use appropriate:\n
\n
* Transactions\n
* Locking\n
* Optimistic concurrency\n
* Idempotency\n
* Queues\n
* Caching\n
* Pagination\n
* Batch processing\n
\n
where required.\n
\n
Do not load large datasets into memory unnecessarily.\n
\n
Never fetch an unlimited database result set.\n
\n
Every potentially large list must support pagination, cursor-based pagination, filtering, or another appropriate limiting strategy.\n
\n
---\n
\n
# Database\n
\n
Treat the database as a critical shared resource.\n
\n
Avoid:\n
\n
* N+1 queries\n
* Unindexed filtering\n
* Unindexed joins on large datasets\n
* Full table scans\n
* SELECT *\n
* Excessive query counts\n
* Database calls inside loops\n
* Large synchronous bulk operations\n
\n
Consider indexing whenever introducing:\n
\n
* Search fields\n
* Foreign keys\n
* Frequently filtered columns\n
* Frequently sorted columns\n
* High-volume joins\n
\n
Database constraints should enforce important data integrity rules whenever possible.\n
\n
Use transactions when an operation modifies multiple related pieces of data.\n
\n
Migrations must be safe for production environments.\n
\n
Consider the impact of schema changes on large tables and running application instances.\n
\n
Never assume the database is empty or small.\n
\n
---\n
\n
# Performance\n
\n
Performance must be considered during implementation, not added as an afterthought.\n
\n
Avoid premature micro-optimization, but identify obvious scalability bottlenecks before introducing them.\n
\n
Expensive work that does not need to happen synchronously should be handled asynchronously.\n
\n
Examples include:\n
\n
* Email\n
* File processing\n
* Large imports\n
* Large exports\n
* Image processing\n
* Report generation\n
* External synchronization\n
* Batch operations\n
\n
Use caching when it provides meaningful benefit, but always define a valid invalidation strategy.\n
\n
Never introduce caching without understanding when cached data becomes stale.\n
\n
---\n
\n
# APIs\n
\n
APIs must be predictable, consistent, secure, and versionable.\n
\n
Use established HTTP semantics and appropriate status codes.\n
\n
API responses should have consistent structures.\n
\n
Validation errors must be machine-readable.\n
\n
Errors must never expose:\n
\n
* Stack traces\n
* Credentials\n
* Internal infrastructure information\n
* Database internals\n
* Secrets\n
\n
Design APIs so clients can safely retry requests where appropriate.\n
\n
Use idempotency for operations where duplicate requests could cause unwanted side effects.\n
\n
Always consider backward compatibility before changing an existing API contract.\n
\n
Avoid breaking changes whenever possible.\n
\n
---\n
\n
# Security\n
\n
Security is mandatory and part of the architecture.\n
\n
Follow secure-by-default principles.\n
\n
Always validate untrusted input.\n
\n
Always implement authorization server-side.\n
\n
Never rely solely on frontend permission checks.\n
\n
Apply least-privilege principles.\n
\n
Protect against common vulnerabilities including:\n
\n
* SQL injection\n
* XSS\n
* CSRF\n
* SSRF\n
* Broken access control\n
* Insecure direct object references\n
* Command injection\n
* Path traversal\n
* Unsafe file uploads\n
* Mass assignment\n
* Sensitive information disclosure\n
\n
Never hardcode:\n
\n
* Passwords\n
* API keys\n
* Tokens\n
* Certificates\n
* Private keys\n
* Connection secrets\n
\n
Secrets belong in appropriate environment or secret-management systems.\n
\n
Sensitive information must not be unnecessarily logged.\n
\n
---\n
\n
# Authentication and Authorization\n
\n
Authentication and authorization are separate concerns.\n
\n
Every protected operation must explicitly enforce authorization.\n
\n
Do not assume that because a user can access an endpoint they are authorized to access every resource handled by that endpoint.\n
\n
Prefer explicit permission models such as:\n
\n
* Roles\n
* Permissions\n
* Policies\n
* Voters\n
* Claims\n
\n
depending on the framework.\n
\n
Design authorization so it remains manageable as the application grows.\n
\n
---\n
\n
# Error Handling\n
\n
Failures are expected in production systems.\n
\n
Handle errors deliberately.\n
\n
Do not silently swallow exceptions.\n
\n
Failures should:\n
\n
* Be logged appropriately\n
* Produce understandable user-facing messages\n
* Preserve diagnostic information for developers\n
* Avoid leaking sensitive technical details\n
\n
External systems must be treated as unreliable.\n
\n
Consider:\n
\n
* Timeouts\n
* Retries\n
* Exponential backoff\n
* Circuit breakers\n
* Partial failures\n
* Duplicate responses\n
* Unavailable services\n
\n
Never allow one unreliable external integration to unnecessarily destabilize the entire application.\n
\n
---\n
\n
# Logging and Observability\n
\n
Production software must be observable.\n
\n
Important operations should generate structured logs.\n
\n
Logs should contain enough context to investigate failures, including where appropriate:\n
\n
* Request ID\n
* Correlation ID\n
* User ID\n
* Job ID\n
* Entity ID\n
* Operation\n
* Duration\n
\n
Do not log secrets or sensitive personal information unnecessarily.\n
\n
Long-running operations should expose meaningful progress or status where appropriate.\n
\n
Important systems should be designed to support:\n
\n
* Metrics\n
* Monitoring\n
* Health checks\n
* Distributed tracing\n
* Alerting\n
\n
---\n
\n
# Background Jobs\n
\n
Background jobs must be assumed to run concurrently.\n
\n
Jobs should preferably be:\n
\n
* Idempotent\n
* Retryable\n
* Observable\n
* Independently executable\n
\n
Do not assume a job runs exactly once.\n
\n
Prevent duplicate processing where necessary.\n
\n
Failed jobs must not disappear silently.\n
\n
Use dead-letter handling or equivalent mechanisms where appropriate.\n
\n
---\n
\n
# Code Quality\n
\n
Write code for the next developer, not only for the compiler.\n
\n
Code should be:\n
\n
* Readable\n
* Predictable\n
* Explicit\n
* Consistent\n
* Easy to test\n
* Easy to modify\n
\n
Prefer descriptive names over abbreviations.\n
\n
Functions and methods should have one clear responsibility.\n
\n
Avoid excessively large:\n
\n
* Classes\n
* Services\n
* Components\n
* Controllers\n
* Methods\n
\n
Extract concepts when they represent meaningful domain or architectural responsibilities.\n
\n
Do not create abstractions purely to reduce line count.\n
\n
Comments should explain **why**, not restate **what** the code already says.\n
\n
---\n
\n
# Type Safety\n
\n
Use the strongest practical type system supported by the language and framework.\n
\n
Avoid ambiguous structures when a defined type, DTO, value object, interface, enum, or schema would provide stronger guarantees.\n
\n
Do not pass unstructured arrays or generic objects through multiple application layers when a proper model should exist.\n
\n
Make invalid states difficult to represent.\n
\n
---\n
\n
# Testing\n
\n
Important business logic requires automated tests.\n
\n
Prefer a balanced combination of:\n
\n
* Unit tests\n
* Integration tests\n
* API tests\n
* End-to-end tests\n
\n
Do not test framework internals.\n
\n
Test application behavior.\n
\n
Always consider edge cases such as:\n
\n
* Empty data\n
* Invalid input\n
* Unauthorized access\n
* Duplicate requests\n
* Concurrent modifications\n
* External service failures\n
* Very large datasets\n
* Boundary values\n
\n
Bug fixes should include a regression test whenever practical.\n
\n
---\n
\n
# Frontend and UX\n
\n
The frontend must look and behave like a polished enterprise application.\n
\n
A feature is not complete merely because it technically works.\n
\n
Every workflow should feel intentional.\n
\n
Interfaces must be:\n
\n
* Consistent\n
* Clear\n
* Responsive\n
* Predictable\n
* Accessible\n
* Efficient\n
* Visually professional\n
\n
Reuse a consistent design system.\n
\n
Do not invent different interaction patterns for equivalent actions.\n
\n
Maintain consistent:\n
\n
* Typography\n
* Spacing\n
* Colors\n
* Border radii\n
* Buttons\n
* Forms\n
* Tables\n
* Modals\n
* Notifications\n
* Icons\n
* Navigation\n
\n
The application should visually appear to come from one professional product team.\n
\n
---\n
\n
# User Flows\n
\n
Always think through the complete user journey.\n
\n
For every feature ask:\n
\n
* How does the user discover this feature?\n
* What is the most obvious next action?\n
* What happens while data loads?\n
* What happens when no data exists?\n
* What happens when an error occurs?\n
* What happens when the operation succeeds?\n
* Can the user accidentally execute the action twice?\n
* Can the user recover from a mistake?\n
* Is confirmation required for destructive actions?\n
* Is the workflow still usable with hundreds or thousands of records?\n
\n
Never leave users on ambiguous screens.\n
\n
Every operation should provide appropriate feedback.\n
\n
---\n
\n
# UI States\n
\n
Every data-driven component should consider at least:\n
\n
* Loading state\n
* Empty state\n
* Success state\n
* Error state\n
* Permission-denied state\n
\n
Buttons performing asynchronous operations should indicate progress and prevent accidental duplicate execution where necessary.\n
\n
Long operations must never make the application appear frozen.\n
\n
---\n
\n
# Forms\n
\n
Forms must provide clear validation.\n
\n
Whenever practical, validation feedback should appear close to the affected field.\n
\n
Preserve user input after validation failures.\n
\n
Clearly distinguish between:\n
\n
* Required fields\n
* Optional fields\n
* Invalid values\n
* Disabled fields\n
* Read-only information\n
\n
Destructive actions must be visually and behaviorally distinct from ordinary actions.\n
\n
---\n
\n
# Tables and Large Data Sets\n
\n
Enterprise applications frequently contain large tables.\n
\n
Tables should support appropriate combinations of:\n
\n
* Pagination\n
* Search\n
* Filtering\n
* Sorting\n
* Column configuration\n
* Bulk actions\n
\n
Never assume users only have a few records.\n
\n
Avoid rendering thousands of DOM elements unnecessarily.\n
\n
Use server-side processing or virtualization where appropriate.\n
\n
---\n
\n
# Accessibility\n
\n
Follow established accessibility standards such as WCAG where practical.\n
\n
Interfaces must remain usable with:\n
\n
* Keyboard navigation\n
* Screen readers\n
* Different screen sizes\n
* Browser zoom\n
* High-content-density scenarios\n
\n
Do not communicate important states exclusively through color.\n
\n
---\n
\n
# Responsive Design\n
\n
Interfaces must behave correctly across supported screen sizes.\n
\n
Desktop enterprise workflows may be optimized for desktop usage, but layouts must degrade gracefully on smaller screens.\n
\n
Avoid arbitrary fixed dimensions where responsive layout techniques are more appropriate.\n
\n
---\n
\n
# Consistency Over Cleverness\n
\n
Prefer established patterns over clever solutions.\n
\n
A developer familiar with the ecosystem should be able to understand the architecture without reverse-engineering unconventional patterns.\n
\n
Follow existing project conventions unless there is a strong reason to improve them.\n
\n
When changing an established convention, apply the change consistently rather than creating two competing approaches.\n
\n
---\n
\n
# Dependencies\n
\n
Before adding a dependency, evaluate:\n
\n
* Is it actively maintained?\n
* Is it widely used?\n
* Does it have known security problems?\n
* Is the functionality significant enough to justify another dependency?\n
* Could the framework already provide the same functionality?\n
\n
Avoid unnecessary dependencies.\n
\n
Do not reimplement mature security-critical functionality yourself.\n
\n
---\n
\n
# Compatibility and Change Management\n
\n
Treat existing production behavior as a contract.\n
\n
Before modifying an existing feature, consider:\n
\n
* Existing clients\n
* Existing API consumers\n
* Existing database records\n
* Existing integrations\n
* Existing user workflows\n
\n
Prefer backwards-compatible changes.\n
\n
If a breaking change is unavoidable, make it explicit and provide a migration path.\n
\n
---\n
\n
# Definition of Done\n
\n
A task is not complete simply because the happy path works.\n
\n
Before considering work finished, verify:\n
\n
1. Architecture is consistent with the existing system.\n
2. Code follows framework and language best practices.\n
3. Authorization is enforced.\n
4. Input is validated.\n
5. Error scenarios are handled.\n
6. Database access is efficient.\n
7. Concurrent execution is safe where relevant.\n
8. Large datasets have been considered.\n
9. The implementation can operate across multiple application instances.\n
10. Logs provide enough information for troubleshooting.\n
11. Relevant automated tests exist.\n
12. Loading, empty, error, and success states exist in the UI where applicable.\n
13. The user flow is intuitive.\n
14. The result visually matches the rest of the application.\n
15. No secrets or sensitive data are exposed.\n
16. Existing functionality and API contracts remain intact.\n
17. The solution would still be reasonable if usage increased by an order of magnitude.\n
\n
---\n
\n
# Decision Rule\n
\n
Whenever multiple implementations are possible, prefer the solution that would be expected from an experienced engineering team maintaining a long-lived enterprise product.\n
\n
Do not ask:\n
\n
> "What is the fastest way to make this work?"\n
\n
Ask:\n
\n
> "What solution would we be comfortable operating, debugging, extending, and securing in production for the next five years with thousands of concurrent users?"\n
\n
The final result must not feel like a prototype, proof of concept, generated demo, or internal tool unless explicitly requested.\n
\n
It should feel like a mature enterprise product built by an experienced professional software engineering team.\n
\n
## Testing Rules\n
\n
_No project-specific instructions._\n
\n
## Git Rules\n
\n
_No project-specific instructions._\n
\n
## Security Rules\n
\n
_No project-specific instructions._\n
\n
## Documentation\n
\n
_No project-specific instructions._\n
"""
-promptTemplateVersionId: Symfony\Component\Uid\UuidV7 {#1086 …}
-projectInstructionVersionId: Symfony\Component\Uid\UuidV7 {#1110 …}
-workingDirectory: null
-branch: null
-baseCommitHash: null
-commitHash: null
-result: []
-error: null
-exitCode: null
-claimedAt: null
-leaseExpiresAt: null
-startedAt: null
-finishedAt: null
-cancelRequestedAt: null
-createdAt: DateTimeImmutable @1789920881 {#1111
date: 2026-09-20 16:14:41.0 +00:00
}
-updatedAt: DateTimeImmutable @1789920881 {#1112
date: 2026-09-20 16:14:41.0 +00:00
}
} |