dsl400 · October 10, 2025 17:53
diff --git a/gistfile1.txt b/gistfile1.txt

 ## 🛠️ **Technology Stack & Preferences**

 ### Backend (Go)
 - **Database**: pgx/v5/pgxpool (never use database/sql)
 - **CLI**: urfave/cli/v2 for command-line interfaces
 - **Web Framework**: Gin for HTTP APIs
 - **Configuration**: Environment variables over JSON config files
 - **Logging**: Structured logging with logrus
 - **Migrations**: Pressly goose for database migrations

 ### Frontend (Next.js)
 - **Framework**: Next.js 15.2.4 with React 19
 - **Styling**: Tailwind CSS with Radix UI components
 - **State Management**: Zustand for global state
 - **Testing**: Jest + React Testing Library + Playwright
 - **Build**: TypeScript with strict mode enabled

 ### Angular Development Guidelines
 **CRITICAL**: Angular applications must follow strict architectural patterns for maintainability and performance.

 #### Template and Style Separation
 **MANDATORY**: Separate templates and styles from component logic.

 **❌ FORBIDDEN - Inline Templates (Multi-line)**:
 ```typescript
 @Component({
  selector: 'app-user',
  template: `
    <div class="user-container">
      <h1>{{user.name}}</h1>
      <p>{{user.email}}</p>
    </div>
  `
 })
 ```

 **✅ REQUIRED - External Template Files**:
 ```typescript
 @Component({
  selector: 'app-user',
  templateUrl: './user.component.html',
  styleUrls: ['./user.component.scss']
 })
 ```

 **❌ FORBIDDEN - Inline Styles**:
 ```typescript
 @Component({
  selector: 'app-user',
  styles: [`
    .user-container { padding: 20px; }
    h1 { color: blue; }
  `]
 })
 ```

 #### Template Best Practices
 **MANDATORY**: Avoid unnecessary wrapper elements and inline styling.

 **❌ FORBIDDEN - Unnecessary Div Wrappers for Structural Directives**:
 ```html
 <div *ngIf="show">
    <app-my-component></app-my-component>
 </div>
 ```

 **✅ REQUIRED - Direct Structural Directives**:
 ```html
 <app-my-component *ngIf="show"></app-my-component>
 ```

 **✅ ALTERNATIVE - Use ng-container When Wrapper Needed**:
 ```html
 <ng-container *ngIf="show">
    <app-my-component></app-my-component>
    <app-other-component></app-other-component>
 </ng-container>
 ```

 **❌ FORBIDDEN - Div Wrappers for Styling**:
 ```html
 <div class="my-class">
    <app-my-component></app-my-component>
 </div>
 ```

 **✅ REQUIRED - Direct Class Application**:
 ```html
 <app-my-component class="my-class"></app-my-component>
 ```

 **❌ FORBIDDEN - Inline CSS Styles**:
 ```html
 <app-my-component style="color: red; margin: 10px;"></app-my-component>
 ```

 **✅ REQUIRED - CSS Classes**:
 ```html
 <app-my-component class="error-state"></app-my-component>
 ```

 #### Architectural Principles
 - **Separation of Concerns**: Templates, styles, and logic in separate files
 - **Component Composition**: Favor composition over wrapper elements
 - **CSS Architecture**: Use CSS classes over inline styles
 - **Performance**: Minimize DOM elements and avoid unnecessary wrappers
 - **Maintainability**: External files enable better tooling and collaboration

 ### Development Environment
 - **Database**: `docker compose up postgres -d`
 - **Backend**: `air` in `./server` (with `--reset-schema` for schema reload)
 - **Frontend**: `npm run dev` in `./frontend`
 - **Testing**: Playwright for end-to-end testing
 - **Credentials**: [email protected] / TestPass123



 ## 📁 **Code Organization & Standards**

 ### File Organization Rules

 **CRITICAL**: Follow strict file organization to maintain clean project structure:

 **Documentation (Diataxis Framework)**:
 - **REQUIRED**: All documentation MUST follow the Diataxis framework
 - **Tutorials** (`./docs/tutorials/`): Learning-oriented, step-by-step guides for beginners
 - **How-To Guides** (`./docs/how-to-guides/`): Task-oriented, problem-solving guides
 - **Explanation** (`./docs/explanation/`): Understanding-oriented, conceptual explanations
 - **Reference** (`./docs/reference/`): Information-oriented, technical descriptions
 - **FORBIDDEN**: Documentation files in project root (except README.md)

 **Development Artifacts**:
 - **Progress Reports**: MUST be placed in `./reports/` directory
  - Examples: implementation summaries, completion reports, status updates
  - FORBIDDEN: Reports in project root or random locations
 - **Development Scripts**: MUST be placed in `./dev-scripts/` directory
  - Examples: verification scripts, test helpers, development utilities
  - FORBIDDEN: Scripts in project root (except standard files like docker-compose.yml)

 **Standard Project Files** (allowed in root):
 - `README.md`, `.env`, `.env.example`, `.gitignore`
 - `docker-compose.yml`, `Dockerfile`
 - `package.json`, `go.mod`, `Cargo.toml` (language-specific)

 **Rationale**:
 - Clean project root improves navigation and professionalism
 - Diataxis framework ensures documentation is findable and useful
 - Consistent organization reduces cognitive load
 - Easier to maintain and onboard new developers

 ### Mandatory Documentation Header
 **REQUIRED**: Every source file (except .md) must begin with this header:

 ```go
 /**
 * ACME - [Component/Service/Module Name]
 *
 * [Concise description: file purpose, scope, and role in architecture]
 *
 * 📚 DOCUMENTATION LINKS:
 * - ./docs/[relevant-doc-file].md
 * - ./docs/architecture/overview.md
 * - ./docs/technical/[specific-component].md
 *
 * 🏗️ ARCHITECTURAL PRINCIPLES:
 * - Follow ACME modular design (high cohesion, low coupling)
 * - Respect system integration contracts and interfaces
 * - Maintain domain-driven design boundaries
 *
 * 🔧 DEVELOPMENT RULES:
 * - Update this header whenever functionality changes
 * - Never leave outdated or misleading comments
 * - Follow existing code patterns (naming, error handling, async flows)
 * - Integrate with observability (logging, metrics) where applicable
 * - IMPORTANT: Do not create large files, extract methods into separate files
 *
 * 💡 USAGE EXAMPLES:
 * - [Example instantiation or usage pattern]
 * - [Integration snippet with other services/components]
 *
 * ⚠️ IMPORTANT:
 * - Do not bypass architectural constraints
 * - No hidden side effects or undocumented dependencies
 * - All integrations must be explicitly documented
 */
 ```

 ### Naming Conventions
 - **Constants**: Add to `./server/rz/constants.go` with `RZ_` prefix
 - **Packages/Modules**: Prefix with `rz`, `Rz`, or `RZ_` depending on context
 - **Files**: Keep small, extract methods to separate files for readability
 - **No magic words**: All constants must be defined and documented

 ### File Organization
 - **Keep files small**: Extract functions/methods into separate files or packages
 - **High cohesion, low coupling**: Group related functionality together
 - **Domain-driven design**: Respect business domain boundaries
 - **Separation of concerns**: Clear separation between layers

 ## 🧪 **Testing Methodology (Critical)**

 ### Test-Driven Development (TDD)
 **MANDATORY**: Always start development by:
 1. Checking if tests exist for the task
 2. Creating tests if none exist
 3. Implementing functionality to make tests pass
 4. Never consider work complete if tests don't pass

	## 🛠️ Technology Stack & Preferences

	### Backend (Go)
	- Database: pgx/v5/pgxpool (never use database/sql)
	- CLI: urfave/cli/v2 for command-line interfaces
	- Web Framework: Gin for HTTP APIs
	- Configuration: Environment variables over JSON config files
	- Logging: Structured logging with logrus
	- Migrations: Pressly goose for database migrations

	### Frontend (Next.js)
	- Framework: Next.js 15.2.4 with React 19
	- Styling: Tailwind CSS with Radix UI components
	- State Management: Zustand for global state
	- Testing: Jest + React Testing Library + Playwright
	- Build: TypeScript with strict mode enabled

	### Angular Development Guidelines
	CRITICAL: Angular applications must follow strict architectural patterns for maintainability and performance.

	#### Template and Style Separation
	MANDATORY: Separate templates and styles from component logic.

	❌ FORBIDDEN - Inline Templates (Multi-line):
	```typescript
	@Component({
	selector: 'app-user',
	template: `
	<div class="user-container">
	<h1>{{user.name}}</h1>
	<p>{{user.email}}</p>
	</div>
	`
	})
	```

	✅ REQUIRED - External Template Files:
	```typescript
	@Component({
	selector: 'app-user',
	templateUrl: './user.component.html',
	styleUrls: ['./user.component.scss']
	})
	```

	❌ FORBIDDEN - Inline Styles:
	```typescript
	@Component({
	selector: 'app-user',
	styles: [`
	.user-container { padding: 20px; }
	h1 { color: blue; }
	`]
	})
	```

	#### Template Best Practices
	MANDATORY: Avoid unnecessary wrapper elements and inline styling.

	❌ FORBIDDEN - Unnecessary Div Wrappers for Structural Directives:
	```html
	<div *ngIf="show">
	<app-my-component></app-my-component>
	</div>
	```

	✅ REQUIRED - Direct Structural Directives:
	```html
	<app-my-component *ngIf="show"></app-my-component>
	```

	✅ ALTERNATIVE - Use ng-container When Wrapper Needed:
	```html
	<ng-container *ngIf="show">
	<app-my-component></app-my-component>
	<app-other-component></app-other-component>
	</ng-container>
	```

	❌ FORBIDDEN - Div Wrappers for Styling:
	```html
	<div class="my-class">
	<app-my-component></app-my-component>
	</div>
	```

	✅ REQUIRED - Direct Class Application:
	```html
	<app-my-component class="my-class"></app-my-component>
	```

	❌ FORBIDDEN - Inline CSS Styles:
	```html
	<app-my-component style="color: red; margin: 10px;"></app-my-component>
	```

	✅ REQUIRED - CSS Classes:
	```html
	<app-my-component class="error-state"></app-my-component>
	```

	#### Architectural Principles
	- Separation of Concerns: Templates, styles, and logic in separate files
	- Component Composition: Favor composition over wrapper elements
	- CSS Architecture: Use CSS classes over inline styles
	- Performance: Minimize DOM elements and avoid unnecessary wrappers
	- Maintainability: External files enable better tooling and collaboration

	### Development Environment
	- Database: `docker compose up postgres -d`
	- Backend: `air` in `./server` (with `--reset-schema` for schema reload)
	- Frontend: `npm run dev` in `./frontend`
	- Testing: Playwright for end-to-end testing
	- Credentials: [email protected] / TestPass123



	## 📁 Code Organization & Standards

	### File Organization Rules

	CRITICAL: Follow strict file organization to maintain clean project structure:

	Documentation (Diataxis Framework):
	- REQUIRED: All documentation MUST follow the Diataxis framework
	- Tutorials (`./docs/tutorials/`): Learning-oriented, step-by-step guides for beginners
	- How-To Guides (`./docs/how-to-guides/`): Task-oriented, problem-solving guides
	- Explanation (`./docs/explanation/`): Understanding-oriented, conceptual explanations
	- Reference (`./docs/reference/`): Information-oriented, technical descriptions
	- FORBIDDEN: Documentation files in project root (except README.md)

	Development Artifacts:
	- Progress Reports: MUST be placed in `./reports/` directory
	- Examples: implementation summaries, completion reports, status updates
	- FORBIDDEN: Reports in project root or random locations
	- Development Scripts: MUST be placed in `./dev-scripts/` directory
	- Examples: verification scripts, test helpers, development utilities
	- FORBIDDEN: Scripts in project root (except standard files like docker-compose.yml)

	Standard Project Files (allowed in root):
	- `README.md`, `.env`, `.env.example`, `.gitignore`
	- `docker-compose.yml`, `Dockerfile`
	- `package.json`, `go.mod`, `Cargo.toml` (language-specific)

	Rationale:
	- Clean project root improves navigation and professionalism
	- Diataxis framework ensures documentation is findable and useful
	- Consistent organization reduces cognitive load
	- Easier to maintain and onboard new developers

	### Mandatory Documentation Header
	REQUIRED: Every source file (except .md) must begin with this header:

	```go
	/**
	* ACME - [Component/Service/Module Name]
	*
	* [Concise description: file purpose, scope, and role in architecture]
	*
	* 📚 DOCUMENTATION LINKS:
	* - ./docs/[relevant-doc-file].md
	* - ./docs/architecture/overview.md
	* - ./docs/technical/[specific-component].md
	*
	* 🏗️ ARCHITECTURAL PRINCIPLES:
	* - Follow ACME modular design (high cohesion, low coupling)
	* - Respect system integration contracts and interfaces
	* - Maintain domain-driven design boundaries
	*
	* 🔧 DEVELOPMENT RULES:
	* - Update this header whenever functionality changes
	* - Never leave outdated or misleading comments
	* - Follow existing code patterns (naming, error handling, async flows)
	* - Integrate with observability (logging, metrics) where applicable
	* - IMPORTANT: Do not create large files, extract methods into separate files
	*
	* 💡 USAGE EXAMPLES:
	* - [Example instantiation or usage pattern]
	* - [Integration snippet with other services/components]
	*
	* ⚠️ IMPORTANT:
	* - Do not bypass architectural constraints
	* - No hidden side effects or undocumented dependencies
	* - All integrations must be explicitly documented
	*/
	```

	### Naming Conventions
	- Constants: Add to `./server/rz/constants.go` with `RZ_` prefix
	- Packages/Modules: Prefix with `rz`, `Rz`, or `RZ_` depending on context
	- Files: Keep small, extract methods to separate files for readability
	- No magic words: All constants must be defined and documented

	### File Organization
	- Keep files small: Extract functions/methods into separate files or packages
	- High cohesion, low coupling: Group related functionality together
	- Domain-driven design: Respect business domain boundaries
	- Separation of concerns: Clear separation between layers

	## 🧪 Testing Methodology (Critical)

	### Test-Driven Development (TDD)
	MANDATORY: Always start development by:
	1. Checking if tests exist for the task
	2. Creating tests if none exist
	3. Implementing functionality to make tests pass
	4. Never consider work complete if tests don't pass
No results found