RABS Coding Standards & Project Structure

This document defines the code conventions, folder structure, and project-wide standards for all source code in the RABS system. It is designed for both human developers and intelligent agents (like Reggie) to ensure consistency, clarity, and long-term maintainability.

---

🧠 Purpose

• Establish coding style consistency across the entire codebase.
• Help AI agents generate and edit code that aligns with human standards.
• Document the folder structure so tools and contributors know where things go.
• Reduce ambiguity in cross-platform development (web, iOS, tvOS, backend).

---

📂 General Folder Structure

The RABS project is modular and supports multi-platform development.

/rabs
├── backend/           # Express API and service logic
├── middleware/        # Shared server-side logic across endpoints
├── frontend-vite/     # React web interface using Vite
├── frontend-next/     # Next.js experimental frontend
├── swift-ios/         # Native iOS app
├── swift-tvos/        # Native Apple TV companion app
├── swift-watchos/     # Native Apple Watch interface
├── shared/            # Universal logic, constants, and rules
├── scripts/           # Automation scripts and CLI utilities
├── docs/              # Central documentation hub
├── data/              # Static datasets / mock data
├── tests/             # Universal test suite and CI entry-point
└── README.md          # Global project overview

---

🧱 General Coding Style

JavaScript / Node.js

Rule	Standard
Indentation	2 spaces
Variable Declaration	const / let (never var)
Functions	Prefer arrow functions () => {}
Semicolons	Always required ;
Imports	Group: 1) built-in 2) external 3) internal
File Extensions	.js, .mjs, .cjs as appropriate

Swift (iOS / watchOS / tvOS)

Rule	Standard
Indentation	4 spaces (Apple default)
Naming	camelCase for vars/functions, PascalCase for types/structs
SwiftUI	Use explicit property wrappers (@State, @Binding, etc.)
Separation	Keep UI and business logic in separate files

JSON / YAML / Config

• Indentation: 2 spaces
• Keys: lowercase or kebab-case (my-key)
• Environment-specific values belong in .env.* files, never hard-coded.

Language-Agnostic Best Practices (from codeRULES.md)

1. Naming

   • Functions are verbs (allocateTransportJob), classes are nouns (VehicleAllocator).
   • Avoid abbreviations unless industry-standard (e.g., NDIS).

2. Error Handling

   • Never swallow errors. Use structured error objects with code, message, details.
   • Log at the edge of the system (middleware/errorHandler.js), return meaningful HTTP codes.

3. Configuration & Secrets

   • All secrets in Vault or .env.local; never commit plaintext.
   • Use 12-Factor CONFIG_ environment variables for runtime behaviour.

4. Security

   • Lint for common vulnerabilities (npm audit, swiftlint, bandit).
   • Sanitize all user input; validate against shared schema definitions.

5. Testing & CI

   • Minimum 80 % branch coverage; PRs failing coverage threshold cannot merge.
   • Fast unit tests live in /tests/unit, slower integration tests in /tests/int.
   • GitHub Actions workflow runs lint → test → build → deploy-preview.

6. Git Workflow

   • Conventional Commit messages (feat:, fix:, docs: …).
   • Feature branches follow username/feature-slug.
   • PR must reference an issue and include a checklist: tests, docs, migration notes.

---

💬 Code Commenting Guidelines

File-Level Comments

Each file begins with a block describing its purpose. For files sanitized for public view, prepend // {K} to any comment you want preserved.

// File: userRouter.js
// Description: Express routes for managing user profiles and auth
// {K} Routes are grouped by feature folder for maintainability

const express = require('express');
const router = express.Router();

Function-Level Comments & RABS Tags

Tags give cognitive and operational context to Reggie and developers.

// ========= [v1 API] /transport/allocate =========
// @methods: POST
// @route:   /api/v1/transport/allocate
// @description:
//   Assigns staff and vehicle to a booking, considering preferences & anomalies.
// @memory:  internalmonologue
// @context: cb_transport
// @selfwrite: true
// @mindmap-ref: transport_context_bucket, transport_bookings
// @model: gpt-4o
// @form-source: /roster/dispatch
// ===============================================
function allocateTransportJob(req, res) {
  // ...
}

Tag Glossary

Tag	Purpose
@memory	Memory store consulted before decision (e.g., internalmonologue).
@context	Specific context bucket providing lessons learned (e.g., cb_transport).
@selfwrite	Whether the agent writes a private reflection after execution.
@mindmap-ref	Named data paths in the mindmap this logic depends on.
@model	LLM used in the decision pipeline (e.g., gpt-4o).
@form-source	UI or API endpoint that originated the request.

---

✅ AI Agent Coding Behaviours

When an AI code assistant (Reggie, Copilot, etc.) generates or edits code it must:

1. Use the correct file extension and language syntax highlighting.
2. Place new files in the appropriate folder according to the structure above.
3. Include a header comment:
   // generated by Reggie :: purpose: <describe task>
4. Avoid hard-coding values that should be config-driven.
5. Reference supporting data files using relative paths.
6. Run npm test / swift test locally (or CI) before committing.

---

🔗 Additional Docs

• Documentation Style Guide
• Project Charter & Vision
• Extended Code Rules