[Docs] Improve README with API Documentation, Setup Guide, and Architecture Overview

[KarenZita01]

Description

The current README.md is minimal and lacks the comprehensive documentation needed for new developers, contributors, and API consumers to understand and work with the EquipChain backend. This issue overhauls the README to serve as a complete project documentation hub covering setup, architecture, API reference, deployment, and contribution guidelines.

The improved README should include the following sections:

Project Overview: Brief description of the EquipChain platform, its purpose (energy metering on Stellar/Soroban), and the backend's role in the architecture.

Quick Start: Step-by-step setup instructions covering: prerequisites (Node.js 20+, npm, Docker), cloning the repository, installing dependencies, configuring environment variables (with a table of all env vars, their defaults, and descriptions), and starting the development server.

API Reference: Summary of all available endpoints grouped by category (System, Auth, Admin, Meters, Analytics, Exports, Webhooks, WebSocket). Each group should list endpoints with methods, paths, brief descriptions, and links to the full OpenAPI docs (once Issue #13 is implemented).

Architecture Overview: Description of the project structure (directory tree with explanations of each directory's purpose), the middleware pipeline order, the service layer, data access layer (repository pattern), and how the app fits together. Include a simple ASCII architecture diagram or a link to a Miro/Excalidraw diagram.

Configuration Reference: Complete table of all environment variables with name, required/optional, default value, description, and example.

Development Guide: Instructions for running tests, linting, building for production, using Docker (with commands from Issue #10), and contributing guidelines (branch naming, PR process, code review standards).

Deployment Guide: Overview of deployment options (Docker, cloud platforms), CI/CD pipeline description, and production considerations (security, monitoring, backups).

Technical Context & Impact

• Dependencies: No code dependencies. Markdown file only. May reference Docker, Docker Compose, and other tools that should be documented.
• Architecture: Single README.md file at the project root. May be supplemented with a CONTRIBUTING.md and docs/ directory for more detailed guides.
• Impact: Directly affects developer onboarding speed, open-source contribution likelihood, and API consumer satisfaction. Poor documentation is consistently cited as a top frustration for developers evaluating a project.

Step-by-Step Implementation Guide

1. Audit Current README: Read the existing README.md and identify what's missing, outdated, or incorrect. Note any information that should be preserved.
2. Write Project Overview: 2-3 paragraphs describing EquipChain, the problem it solves, the tech stack (Express 5, Soroban, Redis, WebSockets), and the project's current status.
3. Write Quick Start Guide: Document step-by-step instructions. Include terminal commands for each step. Add a table of environment variables with all configurable options. Include Docker setup if Issue [DevOps] Containerize Application with Docker Multi-Stage Build and Docker Compose #10 is complete.
4. Write Architecture Section: Describe the directory structure (use a tree output) and explain the role of each directory (src/, tests/, k6/, scripts/, etc.). Describe the request lifecycle through middleware layers.
5. Write API Summary: For each endpoint group, create a table with Method, Path, Description, Auth Required, and link to detailed docs. Keep this high-level — point to OpenAPI for full details.
6. Write Development Guide: Testing instructions, linting, build, Docker usage, contribution workflow. Include a brief style guide (naming conventions, async/await, error handling pattern).
7. Review and Polish: Check for broken links, consistent formatting, proper markdown rendering. Have another team member review.

Verification & Testing Steps

1. Open the README in a markdown previewer (VS Code preview or rendered on GitHub) — verify all sections render correctly, tables are properly formatted, and code blocks have syntax highlighting.
2. Follow the Quick Start guide step-by-step on a fresh machine — verify every command works as documented and the server starts successfully.
3. Click all links in the README — verify none are broken (internal and external).
4. Verify the environment variables table is comprehensive — cross-reference with all .env.example files and source code to ensure no variable is missing.
5. Have a new developer (or team member unfamiliar with the project) follow the setup guide — collect feedback on any unclear steps or missing information.
6. Verify the README includes badges for CI status, license, and Node.js version.