Skip to content

Developer Setup

Bosaj edited this page Oct 24, 2026 · 3 revisions

🛠️ Developer Setup & Architecture Guide

Welcome to the technical implementation guide for L7OT (الحوت).


💻 Tech Stack & Dependencies

  • Frontend Framework: React 19 + TypeScript 5
  • Build Tooling: Vite 8.x + Rollup
  • Styling Engine: Tailwind CSS v4 + @tailwindcss/vite
  • Typography: @fontsource/amiri, @fontsource/ibm-plex-sans-arabic, @fontsource-variable/fraunces, @fontsource-variable/jetbrains-mono
  • Iconography: lucide-react
  • Audio Synthesizer: Pure Web Audio API (SoundEngine with oscillator nodes, biquad filters & gain envelopes)
  • Testing: Vitest 5.x + @testing-library/react + jsdom (26/26 tests passing)
  • Containerization: Multi-stage Docker build with node:22-alpine & nginx:alpine
  • Cloud & Edge Hosting: Netlify Edge CDN & GitHub Pages

🌐 Live Deployments


🚀 Local Development Setup

1. Clone Repository

git clone https://github.com/Bosaj/l7ot.git
cd l7ot

2. Install Packages

npm install

3. Run Development Server

npm run dev

The server will start at http://localhost:5173/.

4. Running the Test Suite

L7OT maintains complete unit and integration test coverage:

# Run all tests once
npm run test

# Run tests in watch mode
npm run test:watch

5. Typecheck & Verification

# Strict TypeScript validation
npm run typecheck

# Full production build
npm run build

🐳 Docker Deployment & Containerization

L7OT is fully containerized with a production multi-stage Dockerfile and docker-compose.yml:

Build and Run with Docker

# Build the Docker image
docker build -t l7ot:latest .

# Run the container exposing port 8080
docker run -d -p 8080:80 --name l7ot-app l7ot:latest

Run with Docker Compose

docker compose up -d

The application is now accessible at http://localhost:8080/ with:

  • Nginx alpine web server with gzip compression.
  • Immutable 1-year browser cache headers for static assets.
  • Full SPA fallback routing (try_files $uri $uri/ /index.html =404;).
  • Content Security Policy & Security headers (X-Frame-Options, X-Content-Type-Options, Referrer-Policy).

🚢 CI/CD & Deployment Workflows

  1. GitHub Actions CI Pipeline (.github/workflows/ci.yml):

    • Runs on every push and pull request to main.
    • Executes strict tsc -b, Vitest test suite, and production vite build.
  2. CodeQL Security Analysis (.github/workflows/codeql.yml):

    • Deep AST static analysis for CWE vulnerabilities.
  3. Deploy to GitHub Pages (.github/workflows/deploy-pages.yml):

    • Deploys production bundle directly to GitHub Pages upon push to main.
  4. Netlify Automated Edge CDN:

    • Configured via netlify.toml and public/_redirects.
    • Instant global caching and zero-downtime atomic deployments.

Clone this wiki locally