This document defines the coding conventions, styles and repository structure for Mealchemy. Compliance with this document ensures uniformity, clarity, flexibility, reliability and efficiency in the codebase.

• Core Engineering Principles
• Frontend (Flutter/Dart)
• Backend (Spring Boot/Java)
• Recommendation Engine (Python)
• Best Practices & Guidelines
• Repository Structure
• Maintenance

DRY (Don't Repeat Yourself)

• Avoid duplication of logic by encouraging reusable components and code. This improves maintainability by ensuring changes are made in one place. DRY works well with modular design.

KISS (Keep It Simple, Stupid)

• Encourages simplicity in design and development. Simple solutions are easier to understand, implement, maintain and use.

• Variables and functions: lowerCamelCase (e.g. loadPantryItems())
• Files: lowercase_with_underscores (e.g. guided_discovery_provider.dart)
• Feature folders: lowercase_with_underscores (e.g. shopping_lists)
• Subfolder structure per feature: lowercase (e.g. models/, providers/, repositories/, screens/, widgets/)
• Test files: mirror source files followed by _test.dart (e.g. source - recipe_provider.dart corresponding test - recipe_provider_test.dart)

• Feature-first, under lib/features/<feature>/, following MVVM (Model, View, ViewModel via Riverpod providers, Repository).
• Shared code lives in lib/core/.

├── frontend/                           ← Flutter mobile app
│   ├── lib/core/                       ← constants, providers, routes, services, shared_widgets, theme, utils
│   ├── lib/features/
│   │   ├── auth/
│   │   ├── dashboard/
│   │   ├── discovery/
│   │   ├── guided_discovery/
│   │   ├── ingredients/
│   │   ├── pantry/
│   │   ├── preference/
│   │   ├── recipe/
│   │   ├── shopping_lists/
│   │   ├── vault/
│   │   └── shared/

• flutter analyze must pass with no warnings before commit.
• Ruleset: default flutter_lints (analysis_options.yaml).

• flutter test with lcov, 80% line coverage enforced.

• Variables and functions: lowerCamelCase (e.g. getPantryIngredientById())
• Classes: PascalCase (e.g. PreferenceService, VaultService)
• Packages: lowercase, no underscores (e.g. shoppinglist, cuisinetype)
• DTO suffixes: for incoming requests, dto file ends in Request.java and for outgoing responses, dto files end in Response.java
• Test files: mirror source class name followed by Test.java (e.g. source - PantryService.java corresponding test - PantryServiceTest.java)
• Integration test files: mirror source controller name followed by IntegrationTest.java (e.g. source - PantryController.java corresponding test - PantryControllerIntegrationTest.java)

• Feature-based packages under com.mealchemy, each following Controller → DTO → Model → Repository → Service .
• Non-feature specific shared code (e.g. enums and exception handling) live in config/ and shared/ instead of in a feature package.
• Database migrations live in a top level database/ directory and have version numbers via Flyway (e.g. V<number>__description.sql).

├── backend/                            ← Backend logic
│   ├── src/main/java/com/mealchemy/
│   │   ├── shoppinglist/
│   │   │        ├── controller/
│   │   │        ├── dto/
│   │   │        ├── model/
│   │   │        ├── repository/
│   │   │        └── service/
|   └── src/test/                       ← Backend unit tests
├──database/                            ← Flyway migration files

• Google Java Style, enforced via the Maven Checkstyle plugin.
• Build fails on any violation.

• JUnit via Maven, JaCoCo, coverage enforced with JaCoCo rules:
  • 80% module wide minimum coverage across instruction, branch and method coverage.
  • Zero-coverage gate - every class that has not been excluded must have at least one covered line.

• Note: to be revised upon implementation

• snake_case for files/functions/variables, PascalCase for classes.

• Ruff for linting/formatting, Mypy for static type checking.

• pytest with pytest-cov, 80% line coverage enforced.

• Consistency: follow all naming conventions, module layout and style across entire codebase
• Code review and CI/CD: no code merges without passing CI (lint + test + coverage) and peer review.
• Security: no secrets or credentials committed to source.
• Error Handling: provide user-friendly, descriptive error messages.
• Dependency management:
  • dependency versions should be explicitly pinned in the configuration files.
  • unused dependencies should be removed during refactoring.

The Mealchemy repository is a monorepo. Everything lives in one repository under the cos301-se-2026 organisation. The top-level structure is:

Mealchemy/
├── .github/
│   ├── workflows/                      ← CI/CD pipeline and automation workflows
│   ├── codecov.yml                     ← Codecov coverage thresholds and flags
│   ├── labeler.yml                     ← PR auto-label rules
│   └── pull_request_template.md
├── .vscode/
│   └── settings.json
├── backend/                            ← Backend logic
│   ├── src/main/java/com/mealchemy/
│   │   ├── auth/
│   │   ├── category/
│   │   ├── config/
│   │   ├── cuisinetype/
│   │   ├── ingredient/
│   │   ├── pantry/
│   │   ├── preference/
│   │   ├── recipe/
│   │   ├── shared/
│   │   ├── shoppinglist/
│   │   ├── unit/
│   │   ├── vault/
│   │   └── MealchemyApplication.java
│   ├── src/main/resources/
│   ├── src/test/                       ← Backend unit tests
│   ├── pom.xml
│   └── mvnw / mvnw.cmd                 ← Maven Wrapper
├── engine/                             ← Python 3.12 recommendation engine
├── frontend/                           ← Flutter mobile app
│   ├── lib/core/                       ← constants, providers, routes, services, shared_widgets, theme, utils
│   ├── lib/features/
│   │   ├── auth/
│   │   ├── dashboard/
│   │   ├── discovery/
│   │   ├── guided_discovery/
│   │   ├── ingredients/
│   │   ├── pantry/
│   │   ├── preference/
│   │   ├── recipe/
│   │   ├── shopping_lists/
│   │   ├── vault/
│   │   └── shared/
│   ├── lib/main.dart
│   ├── test/                           ← core, features, widget_test.dart
│   ├── android/, ios/, macos/          ← platform runner directories (auto-generated by Flutter)
│   └── pubspec.yaml
├── database/                           ← Flyway SQL migration files
├── design-spec/                        ← Brand guide and wireframes (deployed to GitHub Pages)
├── diagrams/
├── docs/
├── infrastructure/                     ← Dockerfiles and docker-compose.yml
├── landing-page/                       ← Static site (assets, scripts, styles, index.html)
├── wiki/                               ← Git submodule pointing at Mealchemy.wiki.git
├── .env.example                        ← Template for local Docker credentials
├── .secrets.example                    ← Template for local act CI secrets
├── .gitleaks.toml                      ← Gitleaks scan configuration
├── .gitmodules                         ← Registers the wiki submodule
├── firebase.json                       ← Firebase Hosting / App Distribution config
├── sonar-project.properties
└── README.md

This is a living document - sections will be expanded on or updated as the codebase changes in future sprints.