Code Guidelines — Paper Surplus Marketplace

This is a summary of coding standards. Full detailed guides are embedded in the respective agent files.

Angular Frontend (Full Guide: .claude/agents/frontend.md)

Key Rules

• Standalone components with OnPush change detection and ViewEncapsulation.None
• Reactive Forms exclusively — never template-driven
• Tailwind CSS exclusively — custom SCSS only when Tailwind can't handle it
• ApexCharts for visualization — never Highcharts
• Feature-based project structure (not type-based)
• BehaviorSubject state in services, exposed via .asObservable()
• takeUntil + _destroy$ pattern for subscription cleanup
• take(1) for one-off subscriptions
• Separate .html files — never inline templates
• Never any — use proper types or unknown
• Barrel exports (index.ts) per feature folder
• NEVER run ng serve — use ng build to verify

Naming

• Files: kebab-case (e.g., surplus-list.component.ts)
• Classes: PascalCase (e.g., SurplusListComponent)
• Interfaces: PascalCase, no I prefix (e.g., SurplusItem)
• Observables: $ suffix (e.g., surplus$)
• Private: _ prefix (e.g., _surplusSubject)

Django Backend (Full Guide: .claude/agents/backend.md)

Key Rules

• PEP 8 + Django coding style
• PostgreSQL always — never SQLite or MySQL
• ModelSerializer with explicit fields — never '__all__'
• ViewSets or GenericAPIView for CRUD operations
• Custom permissions for business logic
• django-filter for query filtering
• drf-spectacular for API documentation
• 12-factor app — environment variables for all config
• Google-style docstrings (Args/Returns/Raises)
• select_related / prefetch_related to avoid N+1 queries
• NEVER run python manage.py runserver — use python manage.py check

Naming

• Files: lowercase_underscores (e.g., surplus_views.py)
• Classes: CamelCase (e.g., SurplusItemSerializer)
• Functions: lowercase_underscores (e.g., get_surplus_by_mill())
• Constants: UPPER_SNAKE_CASE (e.g., MAX_CONTAINER_WEIGHT_KG)
• URLs: kebab-case (e.g., /api/surplus-items/)

Shared Conventions

Git Branching

• Feature branches: feature/<short-description> (e.g., feature/surplus-matching)
• Bug fix branches: fix/<short-description> (e.g., fix/container-weight-calc)
• Main branch: main (protected)
• Develop branch: develop (integration)

Commit Messages

• Descriptive and imperative: "Add surplus item filtering by GSM range"
• Reference issue numbers when applicable
• Keep subject line under 72 characters

Testing

• Frontend: Jasmine/Karma for unit tests, Cypress for E2E
• Backend: Django TestCase for models, APITestCase for APIs
• Write tests for all new code
• Aim for TDD where practical

Code Reviews

• All code goes through PR review
• At least one approval before merge
• Address all review comments