api wiki alignment

.env.example

@@ -1,5 +1,27 @@
-APP_PORT_BACKEND=8888
-MYSQL_DB_HOST=db
-MYSQL_DB_PORT=3311
-MYSQL_DB_UNAME=root
-MYSQL_DB_PASSWD=root
+# ==============================================================================
+# Moo: Twitter Clone - Developer Environment Configuration
+# ==============================================================================
+
+# --- DATABASE CONFIGURATION ---
+# Internal host used by Docker; use 'localhost' if running app natively
+DB_HOST=db
+DB_PORT=3306
+DB_PORT_HOST=3306
+DB_NAME=twitter_clone
+DB_USER=moouser
+DB_PASS=moopass
+DB_ROOT_PASS=rootpass
+
+# --- SECURITY CONFIGURATION ---
+# Minimum 64 characters for high-performance hashing
+JWT_SECRET=9a4f4342453527245a462d4a614e645267556b58703273357638792f423f4528
+JWT_EXPIRATION=3600000
+
+# --- APP PORT CONFIGURATION ---
+# Port exposed to the host machine (avoids 8080 collision)
+HOST_PORT=8082
+ADMINER_PORT=8083
+
+# --- SPRING BOOT CONFIGURATION ---
+SPRING_PROFILES_ACTIVE=prod
+LOGGING_LEVEL_XYZ_SUBHO=INFO

.gitignore

@@ -35,3 +35,4 @@ build/
 .env
 GEMINI.md
 UPGRADE_PROPOSAL.md
+ROBUST_EVOLUTION_PLAN.md

.run/Moo_API.run.xml

@@ -0,0 +1,38 @@
+<!--
+
+    Twitter Backend - Moo: Twitter Clone Application Backend by Scaler
+    Copyright © 2021-2023 Subhrodip Mohanta (hello@subho.xyz)
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+-->
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Moo API" type="SpringBootApplicationConfigurationType" factoryName="Spring Boot">
+    <module name="twitter" />
+    <option name="SPRING_BOOT_MAIN_CLASS" value="xyz.subho.clone.twitter.TwitterBackendApplication" />
+    <option name="ACTIVE_PROFILES" value="dev" />
+    <envs>
+      <env name="DB_HOST" value="localhost" />
+      <env name="DB_PORT" value="3306" />
+      <env name="DB_NAME" value="twitter_clone" />
+      <env name="DB_USER" value="moouser" />
+      <env name="DB_PASS" value="moopass" />
+      <env name="JWT_SECRET" value="9a4f4342453527245a462d4a614e645267556b58703273357638792f423f4528" />
+      <env name="JWT_EXPIRATION" value="3600000" />
+    </envs>
+    <method v="2">
+      <option name="Make" enabled="true" />
+    </method>
+  </configuration>
+</component>

.run/Moo_Dev_Dependencies.run.xml

@@ -0,0 +1,31 @@
+<!--
+
+    Twitter Backend - Moo: Twitter Clone Application Backend by Scaler
+    Copyright © 2021-2023 Subhrodip Mohanta (hello@subho.xyz)
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+-->
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Moo: Dev Dependencies (Docker)" type="docker-deploy" factoryName="docker-compose.yml" server-name="Docker">
+    <deployment type="docker-compose.yml">
+      <settings>
+        <option name="envFilePath" value=".env" />
+        <option name="sourceFilePath" value="docker-compose.dev.yml" />
+        <option name="upDetach" value="false" />
+      </settings>
+    </deployment>
+    <method v="2" />
+  </configuration>
+</component>

.run/Moo_Full_Stack.run.xml

@@ -0,0 +1,31 @@
+<!--
+
+    Twitter Backend - Moo: Twitter Clone Application Backend by Scaler
+    Copyright © 2021-2023 Subhrodip Mohanta (hello@subho.xyz)
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+-->
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Moo: Full Stack (Docker)" type="docker-deploy" factoryName="docker-compose.yml" server-name="Docker">
+    <deployment type="docker-compose.yml">
+      <settings>
+        <option name="envFilePath" value=".env" />
+        <option name="sourceFilePath" value="docker-compose.yml" />
+        <option name="upDetach" value="false" />
+      </settings>
+    </deployment>
+    <method v="2" />
+  </configuration>
+</component>

README.md

@@ -4,7 +4,7 @@
 [![PR Checker](https://github.com/scaleracademy/twitter-backend-java/actions/workflows/pr-checker.yml/badge.svg)](https://github.com/scaleracademy/twitter-backend-java/actions/workflows/pr-checker.yml)
 [![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
 
-An robust, high-performance Twitter clone backend built with the latest
+A robust, high-performance Twitter clone backend built with the latest
 industry standards.
 
 ## Modern Tech Stack
@@ -28,38 +28,30 @@ industry standards.
 
 ### Quick Start
 
-1. **Clone the Repository:**
+Choose the setup that fits your workflow:
 
-    ```bash
-    git clone https://github.com/scaleracademy/twitter-backend-java
-    cd twitter-backend-java
-    ```
+#### Option A: Zero-Installation (Full Stack)
 
-2. **Environment Setup:**
+Ideal for testing or a quick look. Runs everything in Docker.
 
-    ```bash
-    cp .env.example .env
-    # Edit .env with your local MySQL credentials if needed
-    ```
+1. `cp .env.example .env`
+2. `docker compose up -d`
+3. API: `http://localhost:8082` | DB Admin: `http://localhost:8083`
 
-3. **Run with Maven:**
+#### Option B: Native Development (Dependencies Only)
 
-    ```bash
-    ./mvnw spring-boot:run -Dspring-boot.run.profiles=dev
-    ```
+Ideal for coding. Runs DB in Docker, App in your IDE/CLI.
 
-4. **Run with Docker:**
-
-    ```bash
-    docker-compose up -d
-    ```
-
-The API will be available at `http://localhost:8080`.
+1. `cp .env.example .env`
+2. `docker compose -f docker-compose.dev.yml up -d`
+3. Run the **"Moo API"** configuration in IntelliJ IDEA, or use:
+   `./mvnw spring-boot:run -Dspring-boot.run.profiles=dev`
+4. API: `http://localhost:8080` (Standard) | DB Admin: `http://localhost:8083`
 
 ## API Documentation
 
 Access the Interactive Swagger UI at:
-👉 `http://localhost:8080/swagger-ui/index.html`
+👉 `http://localhost:8082/swagger-ui/index.html`
 
 ### Key Endpoints
 

docker-compose.base.yml

@@ -0,0 +1,62 @@
+#
+# Twitter Backend - Moo: Twitter Clone Application Backend by Scaler
+# Copyright © 2021-2023 Subhrodip Mohanta (hello@subho.xyz)
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+#
+# Twitter Backend - Moo: Base Dependencies (Shared)
+#
+
+services:
+  db:
+    image: mysql:8.4
+    container_name: moo-db
+    command: --default-authentication-plugin=mysql_native_password
+    environment:
+      MYSQL_DATABASE: ${DB_NAME:-twitter_clone}
+      MYSQL_USER: ${DB_USER:-moouser}
+      MYSQL_PASSWORD: ${DB_PASS:-moopass}
+      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASS:-rootpass}
+    ports:
+      - "${DB_PORT_HOST:-3306}:3306"
+    volumes:
+      - moo-data:/var/lib/mysql
+    networks:
+      - moo-network
+    healthcheck:
+      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u$$MYSQL_USER", "-p$$MYSQL_PASSWORD"]
+      timeout: 5s
+      retries: 10
+    restart: always
+
+  adminer:
+    image: adminer:latest
+    container_name: moo-adminer
+    ports:
+      - "${ADMINER_PORT:-8083}:8080"
+    depends_on:
+      - db
+    networks:
+      - moo-network
+    restart: always
+
+networks:
+  moo-network:
+    driver: bridge
+
+volumes:
+  moo-data:
+    driver: local

docker-compose.dev.yml

@@ -0,0 +1,24 @@
+#
+# Twitter Backend - Moo: Twitter Clone Application Backend by Scaler
+# Copyright © 2021-2023 Subhrodip Mohanta (hello@subho.xyz)
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+#
+# Twitter Backend - Moo: Developer Dependencies Stack (DB + Adminer)
+#
+
+include:
+  - docker-compose.base.yml

docker-compose.yml

@@ -16,40 +16,35 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #
 
-version: "3"
-
+#
+# Twitter Backend - Moo: Full Stack (API + Dependencies)
+#
+
+include:
+  - docker-compose.base.yml
+
 services:
-
-  db:
-    image: mysql:8
-    container_name: db
-    volumes:
-      - db_data:/var/lib/mysql
-    restart: always
-    hostname: db
-    ports:
-      - "${MYSQL_DB_PORT}:3306"
-    environment:
-      MYSQL_ROOT_PASSWORD: root
-      MYSQL_DATABASE: twitter
-      MYSQL_USER: twitter
-      MYSQL_PASSWORD: twitter
-
-  twitter-backend:
-    depends_on:
-      - db
-    container_name: twitter-backend
+  app:
     build:
       context: .
-      dockerfile: Dockerfile
+      args:
+        JAR_FILE: target/*.jar
+    container_name: moo-api
     ports:
-      - "${APP_PORT_BACKEND}:8080"
-    restart: always
+      - "${HOST_PORT:-8082}:8080"
     environment:
-      MYSQL_DB_HOST: ${MYSQL_DB_HOST}
-      MYSQL_DB_PORT: ${MYSQL_DB_PORT}
-      MYSQL_DB_UNAME: ${MYSQL_DB_UNAME}
-      MYSQL_DB_PASSWD: ${MYSQL_DB_PASSWD}
-
-volumes:
-  db_data: {}
+      - SPRING_PROFILES_ACTIVE=${SPRING_PROFILES_ACTIVE:-prod}
+      - MYSQL_DB_HOST=${DB_HOST:-db}
+      - MYSQL_DB_PORT=${DB_PORT:-3306}
+      - MYSQL_DB_UNAME=${DB_USER:-moouser}
+      - MYSQL_DB_PASSWD=${DB_PASS:-moopass}
+      - JWT_SECRET=${JWT_SECRET}
+      - JWT_EXPIRATION=${JWT_EXPIRATION}
+    depends_on:
+      db:
+        condition: service_healthy
+    restart: always
+    deploy:
+      resources:
+        limits:
+          memory: 512M