Code Guidelines Summary

Angular Frontend Rules

Component Architecture

• Standalone components with OnPush change detection and ViewEncapsulation.None
• Reactive Forms exclusively -- never template-driven forms
• Tailwind CSS exclusively -- custom SCSS only when Tailwind cannot handle it
• ApexCharts for visualization -- never Highcharts
• Feature-based project structure (not type-based)
• Separate .html files -- never inline templates
• Never use any -- use proper types or unknown
• Barrel exports (index.ts) per feature folder

State Management

• BehaviorSubject in services, exposed via .asObservable()
• takeUntil + _destroy$ pattern for subscription cleanup
• take(1) for one-off subscriptions

Naming Conventions

Critical Rules

• NEVER run ng serve -- use ng build to verify changes
• See wiki/concepts/angular-frontend-stack for the full frontend architecture

Django Backend Rules

API Architecture

• ModelSerializer with explicit fields -- never '__all__'
• ViewSets or GenericAPIView for CRUD operations
• Custom permissions for business logic authorization
• django-filter for query filtering
• drf-spectacular for API documentation
• 12-factor app -- environment variables for all configuration
• Google-style docstrings (Args/Returns/Raises)
• select_related / prefetch_related to avoid N+1 queries
• Business logic in services.py, not in views or serializers (see wiki/concepts/service-layer-pattern)

Naming Conventions

Critical Rules

• PostgreSQL always -- never SQLite or MySQL
• NEVER run python manage.py runserver -- use python manage.py check to verify
• See wiki/concepts/django-app-layout for app organization

Git Workflow

Branching Strategy

• 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 mood: "Add surplus item filtering by GSM range"
• Reference issue numbers when applicable
• Subject line under 72 characters

Testing Standards

• 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
• Service tests in tests/test_services/, API tests in tests/test_api/

Code Review Process

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

Sources

• raw/notes/codeGuidelines -- full code guidelines covering Angular, Django, git, and testing conventions

Related

• wiki/concepts/angular-frontend-stack -- frontend architecture that these guidelines apply to
• wiki/concepts/django-app-layout -- backend organization that these guidelines apply to
• wiki/concepts/service-layer-pattern -- the service layer pattern referenced in backend rules
• wiki/summaries/techcontext-summary -- technical stack these guidelines are written for