Zahaawii-stack

Zahaawii-stack is a full-stack platform combining a blog/social media application with a RAG-based AI chatbot.

The system integrates traditional web architecture (Spring + MySQL) with vector-based AI retrieval and controlled tool access via an MCP server.

This repository contains all services, infrastructure configuration, and CI/CD pipelines in a structured mono-repository.

Overview

The platform consists of the following components:

• Blog Backend --- Spring Boot REST API
• Blog Frontend --- Vanilla JavaScript client
• PersonalChatBot --- Node.js (Express) RAG chatbot
• MCP Server --- Spring-based Model Context Protocol server
• Database --- MySQL

The chatbot is designed to:

• Answer questions only when relevant data exists in the vector database
• Retrieve blog content
• Create blog posts through controlled access
• Operate strictly within defined retrieval constraints

All services are containerized and deployed via Docker Compose. Images are built and published to GitHub Container Registry (GHCR) through GitHub Actions workflows.

Architecture

High-Level Design

Client
    |
Apache (Reverse Proxy)
    |
-------------------------------------------------
Blog Backend (Spring) --- /api
Node Backend (Express) --- /node
MCP Server (Spring) --- /mcp
-------------------------------------------------
    |
MySQL + Vector Database

Architectural Principles

• Apache handles public traffic and TLS termination.
• All containers bind to 127.0.0.1 only.
• No container ports are publicly exposed.
• The server never builds application code.
• Deployments use immutable container images.
• Staging and production run in parallel on the same VM using separate Docker Compose projects and ports.

Repository Structure

Zahaawii-stack/

apps/\

• blog-backend/\
• blog-frontend/\
• personalchatbot/\
• mcp-server/

infra/\

• compose/\
• docker-compose.prod.yml\
• docker-compose.staging.yml\
• scripts/\
• deploy.sh

.github/\

• workflows/\
• release.yml

Technology Stack

Backend

• Java
• Spring Boot
• Spring MVC
• JPA / JDBC
• MySQL

Frontend

• Vanilla JavaScript
• HTML
• CSS

AI / RAG

• Node.js (Express)
• Vector database integration
• Model Context Protocol (MCP)

Infrastructure

• Docker
• Docker Compose
• Apache HTTP Server
• GitHub Actions
• GitHub Container Registry (GHCR)
• Linux VM

Environments

Production

• Triggered by pushes to main
• Uses GHCR :prod image tags
• Bound to fixed localhost ports
• Public traffic routed through Apache

Staging

• Triggered by pushes to develop
• Uses GHCR :staging image tags
• Runs in parallel on separate localhost ports

Both environments run simultaneously on the same virtual machine using separate Docker Compose projects.

CI/CD Pipeline

Build and Release Flow

Push to develop: - Build all service images - Tag with :staging and :sha-<commit> - Push to GHCR - Deploy to staging

Push to main: - Build all service images - Tag with :prod and :sha-<commit> - Push to GHCR - Deploy to production

Deployment consists of:

• docker compose pull
• docker compose up -d

Images are immutable and versioned.

Local Development

Requirements

• Docker
• Docker Compose
• Java (for Spring services)
• Node.js (for chatbot if running outside Docker)
• MySQL (if not using containerized database)

Run

docker compose -f infra/compose/docker-compose.staging.yml up --build

Environment Variables

Environment variables are not committed to the repository.

Server structure:

/opt/zahaawii-stack/prod/.env
/opt/zahaawii-stack/staging/.env

Typical variables:

• Database credentials
• API keys
• Vector database configuration
• Application secrets
• GHCR authentication (server side)

Security Considerations

• Containers bind only to 127.0.0.1
• Apache manages TLS termination
• No secrets stored in Git
• Separate staging and production ports
• Strict image versioning via GHCR
• Controlled AI scope through RAG filtering and MCP enforcement

Project Context

Zahaawii-stack is developed as a personal and academic project focused on:

• Full-stack architecture
• AI integration in traditional web systems
• CI/CD automation
• Containerized deployment strategies
• Secure reverse proxy routing

License

Personal and academic project.