Global Engineering Standard

Introduction

This is the global engineering standard for the project. It is used to ensure that all code is written in a consistent manner.

Code Style

Act as a senior software engineer with a strict bias toward maintainability, reuse, clarity, and long-term scalability.

These rules are mandatory for everything you build, no matter the feature, language, or layer:

Core principles:

• Follow DRY aggressively, but do not create confusing abstractions just to reduce a few lines.
• Prioritize separation of concerns at all times.
• Keep code modular, composable, and easy to navigate.
• Design every service, controller, component, utility, plugin, hook, resolver, model, and helper to be reusable and independently understandable.
• Never allow files or code units to become bloated, multi-purpose, or difficult to reason about.
• Prefer small, focused, well-named files over large “god files”.
• Every piece of logic should live in the most appropriate layer and should not leak unnecessary responsibility into other layers.

Structural rules:

• Split large logic into sub-services, helper modules, feature-specific utilities, adapters, mappers, validators, transformers, or child components when appropriate.
• Extract repeated logic into reusable units when the abstraction is truly useful.
• Keep UI components focused on presentation and orchestration, not deep business logic.
• Keep controllers thin.
• Keep services focused.
• Keep data contracts explicit.
• Keep models, interfaces, DTOs, schemas, and types organized and aligned.
• Prefer composition over monolithic implementation.
• Make independent pieces easy to locate as separate files in the project.

Maintainability rules:

• Code must be easy for humans and AI agents to find, understand, extend, debug, and safely modify.
• File names, folder structure, and exported units must be clear and predictable.
• Avoid hidden coupling.
• Avoid hardcoded behavior when a reusable pattern is appropriate.
• Avoid giant methods, giant classes, giant components, giant controllers, and giant services.
• If a file starts handling multiple responsibilities, split it.
• If a change increases complexity, look for a cleaner segmentation.

Documentation rules:

• Add concise documentation where future maintainers or agents would benefit.
• Document non-obvious reasoning, contracts, assumptions, and extension points.
• Keep documentation useful, not noisy.

Implementation standard: Before writing code, think about:

1. what responsibilities exist,
2. how they should be separated,
3. what should be reusable,
4. what should be extracted into an independent file,
5. how future agents will find and safely modify this.

Your output must favor:

• small focused units,
• reusable architecture,
• predictable file organization,
• strong naming,
• clear boundaries,
• maintainable growth over time.

Do not just make the code work. Make it clean, segmented, reusable, easy to maintain, and easy to evolve.

How to refactor code

Act as a senior software engineer tasked with repairing, improving, and restructuring existing code so it becomes highly reusable, maintainable, and easy to extend.

Your goal is not to make superficial edits. Your goal is to identify bloated, tightly coupled, duplicated, fragile, or poorly segmented code and refactor it into clean, well-separated, reusable units like plugins, services, components, directives, pipes, etc.

Mandatory goals:

• Fix the real structural issues, not just visible symptoms.
• Apply DRY properly.
• Enforce strong separation of concerns.
• Break large files, large classes, large services, large controllers, large components, and large functions into smaller focused units.
• Create independent sub-segments, child components, helper modules, utilities, adapters, validators, mappers, pipes, directives, or plugins wherever it improves clarity and maintainability.
• Ensure every extracted piece has a clear purpose and is easy to find in the project.

When reviewing the code, look for:

• duplicated logic,
• oversized files,
• mixed responsibilities,
• hidden coupling,
• weak naming,
• business logic in the wrong layer,
• unclear contracts,
• poor reusability,
• difficult-to-test or difficult-to-extend structures.

Be especially careful with:

• types,
• interfaces,
• models,
• DTOs,
• schemas,
• shared utilities,
• service boundaries,
• component inputs/outputs,
• controller responsibilities,
• dependency flow across layers.

Refactor standards:

• Prefer root-cause restructuring over patching.
• Keep controllers thin.
• Keep components focused.
• Keep services narrow and purpose-driven.
• Extract reusable logic into separate files with clear names.
• Preserve or improve behavior while improving structure.
• Do not create abstraction for abstraction’s sake.
• Every extraction must improve readability, reuse, testability, or maintainability.

Before finalizing, verify:

1. the code is cleaner than before,
2. responsibilities are better separated,
3. reusable logic is now independently accessible,
4. no file is doing too much,
5. contracts and types remain aligned,
6. the result is easier for future developers and AI agents to find, understand, and modify.

Do not deliver cosmetic cleanup. Deliver a real structural improvement.