🌙 Dark Mode
Developer Documentation

MentoraX Systems

Engineering Standards & Best Practices

📋 Purpose & Vision

This document defines the engineering standards, development processes, and best practices for all MentoraX Systems projects. The goal is to ensure:

  • High-quality, maintainable, and scalable systems
  • Consistency across teams and repositories
  • Clear ownership, traceability, and accountability
  • Long-term sustainability of the MentoraX ecosystem
These standards apply to all contributors across design, development, testing, and release stages.

🏷️ Product & Project Identifiers (Mandatory)

Every project, repository, branch, ticket, and release must include the correct project tag.

Product Code
MentoraX Main App MNTX
MentoraX Web LMS MNTXW
MentoraX Backend MNTXBE
NeuroLearn Engine NLE
Teacher App MNTXT

Usage Examples:

Branch:  feature/MXBE-0001/user-auth
Commit:  MXBE-0003: ENHC : add JWT refresh flow
Ticket:  NLE-23

🏗️ System Design Principles

Architecture Principles

🔧

Modular Design

Components must be independently replaceable

📦

Separation of Concerns

UI, domain, application, and infrastructure layers must be isolated

🔌

API-First Thinking

Every core capability exposed via clear contracts

⚙️

Extensibility Over Hardcoding

Rules, configs, and behaviors should be data-driven

Approved Architectural Patterns

Layer Pattern
Backend Layered / Hexagonal Architecture
AI Systems Pipeline-based architecture (Ingestion → Feature → Model → Output)
Frontend Component-based architecture
Integration Event-driven or contract-based APIs

⚡ Development Process

Work Item Flow

All work must follow this lifecycle:

  1. Requirement / Task defined (ticket)
  2. Design clarity (short design note if needed)
  3. Feature branch creation
  4. Development + local testing
  5. Pull Request (PR)
  6. Review + fixes
  7. Merge to main branch
⚠️ No direct commits to main.

🌿 Branching Strategy

Branch Types

Branch Type Purpose Example
main Stable, production-ready main
feature New functionality feature/MNTXW-0002/dashboard-ui
bugfix Non-breaking fixes bugfix/MXBE-0003/null-check
hotfix Critical production fixes hotfix/NLE-0004/model-crash

Rules

  • Always branch from main
  • One feature or fix per branch
  • Keep branches short-lived

💬 Commit Message Standards

Format

<ProjectCode>: <short, clear description>

Examples

NLE-0002: ENHC : add feature normalization step
MNTXT-0004: BUG : fix session timeout bug

Rules

  • Present tense
  • No vague messages ("fix bug")
  • One logical change per commit

🔄 Pull Request (PR) Standards

Every PR must include:

  • Clear title with project code
  • Description of what and why
  • Linked ticket ID
  • Screenshots or logs (if applicable)

PR Checklist

  • Code compiles / runs
  • No unused code or comments
  • Naming follows standards
  • Tests updated or added (if required)
Minimum 1 reviewer required before merge.

💻 Coding Standards

Naming Conventions

General

  • Use meaningful, descriptive names
  • Avoid abbreviations unless domain-standard

Java / Backend

  • Classes: PascalCase → StudentService
  • Wrapper Classes: ID + PascalCase → MNTStudentService
  • Methods & variables: camelCase
  • Constants: MNT_UPPER_SNAKE_CASE

Frontend

  • Components: PascalCase
  • Files: kebab-case
  • Variables: camelCase

AI / Python

  • Files: snake_case
  • Classes: PascalCase
  • Functions: snake_case

Class & Module Design Rules

  • One class = one responsibility
  • Prefer composition over inheritance
  • Avoid god classes and utility overloads
  • Services must not directly access controllers or UI logic
Rule of thumb: If a class explanation needs more than 3 sentences, it's doing too much.

Error Handling & Logging

  • Never swallow exceptions
  • Log contextual information, not just stack traces
  • Do not log sensitive data (PII, credentials)

Log Levels:

  • INFO - normal flow
  • WARN - recoverable issues
  • ERROR - failures needing attention

🧪 Testing Standards

Required Test Types

  • Unit tests for core logic
  • Integration tests for APIs
  • Manual sanity testing before PR

Testing Rules

  • Tests must be deterministic
  • No hardcoded environment dependencies
  • Failing tests block merges

📚 Documentation Standards

Every project must include:

  • README (setup + overview)
  • Architecture overview (diagram or markdown)
  • API documentation (Swagger / OpenAPI)
Code must be self-documenting, not comment-heavy.

🔒 Security & Ethics (Mandatory)

  • Follow least-privilege access
  • Validate all external inputs
  • AI outputs must be explainable and non-decisive
  • Children-related data handled with maximum care
  • No feature should cause harm, stigma, or irreversible labeling

⭐ Quality Culture

At MentoraX Systems:

Correctness > speed
Long-term impact > short-term hacks
Clarity > cleverness
Responsibility > blame
Every engineer is responsible for system quality, not just their code.

We don't just build software.

We build systems that shape the next generation.

This document is a living standard. Improvements must be proposed via PRs and reviewed by the core team.