From 61baf3ac5d0f41a2eb0cc69986fb4378d50fa671 Mon Sep 17 00:00:00 2001 From: FalahMobile Date: Thu, 2 Jul 2026 20:01:48 +0800 Subject: [PATCH] chore: sync all local changes and new files - Update next.config.ts - Add netlify.toml, Docker configs, e2e tests - Add env templates, docs (README, ROADMAP, TODO) - Add vitest/playwright test configs - Add component and lib tests - Add install script, portainer env template - Update .gitignore (tsbuildinfo, deno.lock, dev.db) --- .env.example | 111 ++++++ .env.template | 83 ++++ .github/workflows/qa.yml | 39 ++ .gitignore | 10 + .gitmodules | 51 +++ Makefile | 133 +++++++ README.md | 483 +++++++++++++++++++++++ ROADMAP.md | 68 ++++ TODO.md | 148 +++++++ docker-compose.extras.yml | 148 +++++++ docker-compose.ha.yml | 330 ++++++++++++++++ docker-compose.local.yml | 203 ++++++++++ e2e/auth-flow.spec.ts | 38 ++ halal-monitor-brief.md | 137 +++++++ install.sh | 240 +++++++++++ komodo.toml | 38 ++ netlify.toml | 15 + next.config.ts | 2 +- playwright.config.ts | 26 ++ portainer.env | 20 + src/components/__tests__/Navbar.test.tsx | 41 ++ src/lib/__tests__/auth.test.ts | 76 ++++ tsconfig.tsbuildinfo | 2 +- vitest.config.ts | 15 + vitest.setup.ts | 1 + 25 files changed, 2456 insertions(+), 2 deletions(-) create mode 100644 .env.example create mode 100644 .env.template create mode 100644 .github/workflows/qa.yml create mode 100644 .gitmodules create mode 100755 Makefile create mode 100644 README.md create mode 100644 ROADMAP.md create mode 100644 TODO.md create mode 100644 docker-compose.extras.yml create mode 100644 docker-compose.ha.yml create mode 100644 docker-compose.local.yml create mode 100644 e2e/auth-flow.spec.ts create mode 100644 halal-monitor-brief.md create mode 100755 install.sh create mode 100644 komodo.toml create mode 100644 netlify.toml create mode 100644 playwright.config.ts create mode 100644 portainer.env create mode 100644 src/components/__tests__/Navbar.test.tsx create mode 100644 src/lib/__tests__/auth.test.ts create mode 100644 vitest.config.ts create mode 100644 vitest.setup.ts diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..b49bba1 --- /dev/null +++ b/.env.example @@ -0,0 +1,111 @@ +# Falah OS v1.3 — Environment Variables +# Copy to .env and fill in all values before running. +# Generate secrets with: openssl rand -base64 32 + +# ============================================================================= +# REQUIRED — must be set before starting +# ============================================================================= + +# JWT signing secret — min 32 random characters +JWT_SECRET= + +# Encryption key for sensitive data — min 32 random characters +ENCRYPTION_KEY= + +# Admin secret for privileged operations +ADMIN_SECRET= + +# PostgreSQL password +POSTGRES_PASSWORD= + +# Redis password +REDIS_PASSWORD= + +# iBaaS API Key for EE Gateway +IBAAS_API_KEY=falah-os-ibaas-key-2026 + +# ============================================================================= +# POLAR — required for subscription payments (polar.sh) +# ============================================================================= + +# Get from polar.sh > Settings > Developers > Access Tokens +POLAR_ACCESS_TOKEN= + +# Get from polar.sh > Settings > Webhooks > your endpoint secret +POLAR_WEBHOOK_SECRET= + +# App URL for Polar redirect URLs +NEXT_PUBLIC_APP_URL=http://localhost:3000 + +# ============================================================================= +# AI — required for Nur AI coaching +# ============================================================================= + +OPENCORE_URL=https://opencode.ai/zen/go/v1/chat/completions +OPENCORE_API_KEY= + +# ============================================================================= +# OPTIONAL — have sensible defaults +# ============================================================================= + +NODE_ENV=production + +# Domain name and protocol for URL generation +DOMAIN= +PROTOCOL=https + +# Protocol fee taken by Falah OS (default 1.5%) +PROTOCOL_FEE_PERCENT=1.5 + +# Shariah rules enforced by RAMZ (comma-separated, no spaces) +SHARIAH_RULES=NO_RIBA,NO_GHARAR,NO_MAYSIR,HALAL_COMMODITY,ASSET_BACKED,MUTUAL_CONSENT,NO_BAI_INAH + +# Set to true only in a controlled test environment +ENABLE_CHAOS_TESTING=false + +# ============================================================================= +# LOGGING (optional) +# ============================================================================= + +LOG_LEVEL=info +LOG_FORMAT=json + +# ============================================================================= +# POSTGRES (optional overrides) +# ============================================================================= + +POSTGRES_USER=postgres +POSTGRES_HOST=postgres +POSTGRES_PORT=5432 +# Derived from the above; override per-service database name as needed +DATABASE_URL=postgresql://postgres:${POSTGRES_PASSWORD}@postgres:5432/falahdb + +# ============================================================================= +# REDIS (optional overrides) +# ============================================================================= + +REDIS_HOST=redis +REDIS_PORT=6379 + +# ============================================================================= +# FEATURE FLAGS (optional) +# ============================================================================= + +ENABLE_MOCKNET=false +ENABLE_DEBUG=false + +# ============================================================================= +# MONITORING (optional) +# ============================================================================= + +GRAFANA_PASSWORD= +ALERT_EMAIL= +SLACK_WEBHOOK_URL= + +# ============================================================================= +# BACKUP (optional) +# ============================================================================= + +BACKUP_DIR=/backups +S3_BUCKET= +RETENTION_DAYS=30 diff --git a/.env.template b/.env.template new file mode 100644 index 0000000..d05230f --- /dev/null +++ b/.env.template @@ -0,0 +1,83 @@ +# Falah OS v1.3 Production Environment Template +# Copy this to .env and fill in the values + +# ============================================================================= +# CORE CONFIGURATION +# ============================================================================= +NODE_ENV=production +DOMAIN=falah-os.com +PROTOCOL=https + +# ============================================================================= +# SECURITY - GENERATE WITH: openssl rand -base64 32 +# ============================================================================= +JWT_SECRET=CHANGE_ME_generate_secure_random_string +ENCRYPTION_KEY=CHANGE_ME_generate_secure_random_string +ADMIN_SECRET=CHANGE_ME_generate_secure_random_string + +# ============================================================================= +# DATABASE - UPDATE credentials for production +# ============================================================================= +POSTGRES_HOST=postgres-primary +POSTGRES_PORT=5432 +POSTGRES_USER=postgres +POSTGRES_PASSWORD=CHANGE_ME_strong_password +POSTGRES_DB=falahdb + +# ============================================================================= +# REDIS - UPDATE password for production +# ============================================================================= +REDIS_HOST=redis-master +REDIS_PORT=6379 +REDIS_PASSWORD=CHANGE_ME_strong_password + +# ============================================================================= +# SERVICE URLs (Internal) +# ============================================================================= +UMMAHID_URL=http://ummahid:3000 +WALLET_URL=http://wallet:3000 +RAMZ_URL=http://ramz:3000 +MOCKNET_URL=http://mocknet:3000 + +# ============================================================================= +# WALLET SERVICE +# ============================================================================= +PROTOCOL_FEE_PERCENT=1.5 + +# ============================================================================= +# RAMZ CONTRACT ENGINE +# ============================================================================= +SHARIAH_RULES=NO_RIBA,NO_GHARAR,NO_MAYSIR,HALAL_COMMODITY,ASSET_BACKED,MUTUAL_CONSENT,NO_BAI_INAH + +# ============================================================================= +# BACKUP CONFIGURATION +# ============================================================================= +BACKUP_DIR=/backups +S3_BUCKET=falah-os-backups +RETENTION_DAYS=30 + +# ============================================================================= +# MONITORING +# ============================================================================= +GRAFANA_PASSWORD=CHANGE_ME_strong_password +ALERT_EMAIL=alerts@falah-os.com +SLACK_WEBHOOK_URL= + +# ============================================================================= +# CDN & EXTERNAL SERVICES +# ============================================================================= +CDN_API_KEY= +CDN_ZONE_ID= + +# ============================================================================= +# LOGGING +# ============================================================================= +LOG_LEVEL=info +LOG_FORMAT=json + +# ============================================================================= +# FEATURE FLAGS +# ============================================================================= +ENABLE_MOCKNET=false +ENABLE_CHAOS_TESTING=false +ENABLE_DEBUG=false \ No newline at end of file diff --git a/.github/workflows/qa.yml b/.github/workflows/qa.yml new file mode 100644 index 0000000..2e9c43e --- /dev/null +++ b/.github/workflows/qa.yml @@ -0,0 +1,39 @@ +name: QA Workflow + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Setup Node 20 + uses: actions/setup-node@v4 + with: + node-version: 20 + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Run Vitest (Unit + Integration) + run: npx vitest run + + - name: Install Playwright Browsers + run: npx playwright install --with-deps chromium + + - name: Run Playwright (E2E) + run: npx playwright test + + - name: Upload Playwright report + uses: actions/upload-artifact@v4 + if: failure() + with: + name: playwright-report + path: playwright-report/ + retention-days: 30 diff --git a/.gitignore b/.gitignore index d812e88..92d093b 100644 --- a/.gitignore +++ b/.gitignore @@ -43,6 +43,16 @@ coverage/ *.sql !infrastructure/postgres/init.sql +# TypeScript +*.tsbuildinfo + +# Deno (not used in this project) +deno.lock + +# SQLite dev database +prisma/dev.db +prisma/dev.db-journal + # Claude (workspace config, not project code) .claude/* !.claude/commands/ diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..9d38023 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,51 @@ +[submodule "falah-os"] + path = falah-os + url = https://github.com/maifors/falah-os.git + +[submodule "ulp-portal"] + path = ulp-portal + url = https://github.com/maifors/ulp-portal.git + +[submodule "falah-os-sdk-py"] + path = falah-os-sdk-py + url = https://github.com/maifors/falah-os-sdk-py.git + +[submodule "falah-os-sdk"] + path = falah-os-sdk + url = https://github.com/maifors/falah-os-sdk.git + +[submodule "falah-os-mocknet"] + path = falah-os-mocknet + url = https://github.com/maifors/falah-os-mocknet.git + +[submodule "alah-os-mocknet"] + path = alah-os-mocknet + url = https://github.com/maifors/alah-os-mocknet.git + +[submodule "falah-os-ummahid"] + path = falah-os-ummahid + url = https://github.com/maifors/falah-os-ummahid.git + +[submodule "falah-os-ramz"] + path = falah-os-ramz + url = https://github.com/maifors/falah-os-ramz.git + +[submodule "falah-os-admin"] + path = falah-os-admin + url = https://github.com/maifors/falah-os-admin.git + +[submodule "falah-os-app"] + path = falah-os-app + url = https://github.com/maifors/falah-os-app.git + +[submodule "falah-os-istore"] + path = falah-os-istore + url = https://github.com/maifors/falah-os-istore.git + +[submodule "falah-os-dev-porta"] + path = falah-os-dev-porta + url = https://github.com/maifors/falah-os-dev-porta.git + +[submodule "falah-os-landing"] + path = falah-os-landing + url = https://github.com/maifors/falah-os-landing.git diff --git a/Makefile b/Makefile new file mode 100755 index 0000000..04585ba --- /dev/null +++ b/Makefile @@ -0,0 +1,133 @@ +.PHONY: help install build up down restart logs health backup deploy clean \ + ummahid-logs wallet-logs ramz-logs mocknet-logs api-logs app-logs \ + db-shell db-backup db-restore redis-shell redis-flush \ + stats ps setup env-check test test-watch test-coverage + +# Falah OS v1.3 — Docker Compose management +# Usage: make help + +help: ## Show available commands + @echo "Falah OS v1.3" + @echo "" + @echo "Usage: make [command]" + @echo "" + @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf " \033[36m%-18s\033[0m %s\n", $$1, $$2}' + +# --------------------------------------------------------------------------- +# Core lifecycle +# --------------------------------------------------------------------------- + +install: ## Full install: generate secrets, write .env, start stack, health check + @bash install.sh + +setup: ## First-time setup: copy .env.example → .env (manual secret entry) + @if [ -f .env ]; then echo ".env already exists, skipping."; else cp .env.example .env && echo "Created .env — fill in secrets before running 'make up'"; fi + +env-check: ## Verify required env vars are set + @missing=0; \ + for var in JWT_SECRET ENCRYPTION_KEY ADMIN_SECRET POSTGRES_PASSWORD REDIS_PASSWORD; do \ + if [ -z "$$(grep -E "^$$var=.+" .env 2>/dev/null | cut -d= -f2)" ]; then \ + echo "MISSING: $$var"; missing=1; \ + fi; \ + done; \ + [ $$missing -eq 0 ] && echo "All required env vars are set." || exit 1 + +test: ## Run all tests + npm test + +test-watch: ## Run tests in watch mode + npm run test:watch + +test-coverage: ## Run tests with coverage report + npm run test:coverage + +build: ## Build all service images + docker compose build + +up: env-check ## Start the full stack + docker compose up -d + @echo "Waiting for services..." + @sleep 8 + @$(MAKE) health + +down: ## Stop and remove containers (preserves volumes) + docker compose down + +restart: ## Restart all containers + docker compose restart + +logs: ## Tail logs from all services + docker compose logs -f --tail=100 + +health: ## Run health checks against all services + @./scripts/health-check.sh + +ps: ## Show container status + docker compose ps + +stats: ## Live container resource usage + docker stats --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.NetIO}}" + +# --------------------------------------------------------------------------- +# Per-service logs +# --------------------------------------------------------------------------- + +ummahid-logs: ## Tail Ummah ID logs + docker compose logs -f ummahid + +wallet-logs: ## Tail Wallet logs + docker compose logs -f wallet + +ramz-logs: ## Tail RAMZ logs + docker compose logs -f ramz + +mocknet-logs: ## Tail Mock-Net logs + docker compose logs -f mocknet + +falahd-logs: ## Tail falahd daemon logs + docker compose logs -f falahd + +api-logs: ## Tail API Gateway logs + docker compose logs -f api-gateway + +app-logs: ## Tail App logs + docker compose logs -f app + +# --------------------------------------------------------------------------- +# Database +# --------------------------------------------------------------------------- + +db-shell: ## Open PostgreSQL shell + docker compose exec postgres psql -U $${POSTGRES_USER:-postgres} + +db-backup: ## Dump all databases to backups/ + @mkdir -p backups + docker compose exec postgres pg_dumpall -U $${POSTGRES_USER:-postgres} \ + | gzip > backups/postgres_$$(date +%Y%m%d_%H%M%S).sql.gz + @echo "Backup saved to backups/" + +db-restore: ## Restore from backup: make db-restore FILE=backups/postgres_xxx.sql.gz + @[ -n "$(FILE)" ] || (echo "Usage: make db-restore FILE=backups/postgres_xxx.sql.gz" && exit 1) + gunzip -c $(FILE) | docker compose exec -T postgres psql -U $${POSTGRES_USER:-postgres} + +# --------------------------------------------------------------------------- +# Redis +# --------------------------------------------------------------------------- + +redis-shell: ## Open Redis CLI + docker compose exec redis redis-cli -a $${REDIS_PASSWORD} + +redis-flush: ## Flush all Redis data (will prompt for confirmation) + @echo "WARNING: this deletes all Redis data." + @read -p "Type 'yes' to confirm: " c && [ "$$c" = "yes" ] || exit 1 + docker compose exec redis redis-cli -a $${REDIS_PASSWORD} FLUSHALL + +# --------------------------------------------------------------------------- +# Cleanup +# --------------------------------------------------------------------------- + +clean: ## Remove containers AND volumes (destroys all data — prompts first) + @echo "WARNING: this destroys all Falah OS containers and volumes." + @read -p "Type 'yes' to confirm: " c && [ "$$c" = "yes" ] || exit 1 + docker compose down -v + @echo "Done. Run 'make up' to start fresh." diff --git a/README.md b/README.md new file mode 100644 index 0000000..b932c9d --- /dev/null +++ b/README.md @@ -0,0 +1,483 @@ +# Falah OS Master - Repository Guide + +## 📚 Overview + +Falah OS Master is a monorepo structure that manages the Falah Operating System ecosystem through Git submodules. This repository contains links to all core modules and services that make up the complete Falah OS platform. + +## 🏗️ Repository Structure + +This project follows a **modular architecture** with the following components: + +``` +Falah-OS-Master/ +├── .gitmodules # Submodule configuration +├── README.md # This file +├── falah-os/ # Core OS +├── ulp-portal/ # User Portal +├── falah-os-sdk-py/ # Python SDK +├── falah-os-sdk/ # Main SDK +├── falah-os-mocknet/ # Mock Network +├── alah-os-mocknet/ # Alternative Mock Network +├── falah-os-ummahid/ # UmmaID Component +├── falah-os-ramz/ # RAMZ Component +├── falah-os-admin/ # Admin Dashboard +├── falah-os-app/ # Main Application +├── falah-os-istore/ # Store Interface +├── falah-os-dev-porta/ # Developer Portal +└── falah-os-landing/ # Landing Page +``` + +## 📋 Module Documentation + +### Core Modules + +| Module | Repository | Purpose | Status | +|--------|-----------|---------|--------| +| **falah-os** | `maifors/falah-os` | Core operating system kernel and runtime | Active | +| **falah-os-sdk** | `maifors/falah-os-sdk` | Main SDK for development | Active | +| **falah-os-sdk-py** | `maifors/falah-os-sdk-py` | Python SDK wrapper | Active | + +### Portal & Interface Modules + +| Module | Repository | Purpose | Status | +|--------|-----------|---------|--------| +| **ulp-portal** | `maifors/ulp-portal` | User Portal Interface | Active | +| **falah-os-admin** | `maifors/falah-os-admin` | Administration Dashboard | Active | +| **falah-os-dev-porta** | `maifors/falah-os-dev-porta` | Developer Portal | Active | +| **falah-os-landing** | `maifors/falah-os-landing` | Marketing Landing Page | Active | + +### Application & Service Modules + +| Module | Repository | Purpose | Status | +|--------|-----------|---------|--------| +| **falah-os-app** | `maifors/falah-os-app` | Main Application | Active | +| **falah-os-istore** | `maifors/falah-os-istore` | App Store Interface | Active | + +### Identity & Network Modules + +| Module | Repository | Purpose | Status | +|--------|-----------|---------|--------| +| **falah-os-ummahid** | `maifors/falah-os-ummahid` | Identity Management (UmmaID) | Active | +| **falah-os-ramz** | `maifors/falah-os-ramz` | RAMZ Protocol/Service | Active | + +### Testing & Infrastructure Modules + +| Module | Repository | Purpose | Status | +|--------|-----------|---------|--------| +| **falah-os-mocknet** | `maifors/falah-os-mocknet` | Mock Network for Testing | Active | +| **alah-os-mocknet** | `maifors/alah-os-mocknet` | Alternative Mock Network | Active | + +--- + +## 🚀 Getting Started + +### Prerequisites + +- Git (v2.13+) +- Basic Unix/Linux knowledge +- Access to all submodule repositories + +### Initial Setup + +#### Clone the Repository with All Submodules + +```bash +# Clone with recursive submodules initialization +git clone --recurse-submodules https://github.com/Falah-Consultancy-Limited/Falah-OS-Master.git + +# Navigate to the repository +cd Falah-OS-Master +``` + +#### If Already Cloned Without Submodules + +```bash +# Initialize and fetch all submodules +git submodule update --init --recursive + +# Or use the shorthand +git submodule init +git submodule update +``` + +#### Update All Submodules to Latest + +```bash +# Fetch the latest commits from all submodules +git submodule foreach git pull origin main + +# Or use the parallel version (Git 2.8+) +git submodule foreach --parallel git pull origin main +``` + +--- + +## 📖 Development Workflow (SDLC) + +### Phase 1: Planning & Requirements + +1. **Issue Creation**: Create GitHub issues for new features/bugs +2. **Milestone Assignment**: Assign to relevant milestones +3. **Documentation**: Update module documentation if affected + +### Phase 2: Development + +#### Branch Strategy (Git Flow) + +``` +main (production) + └── develop (staging) + ├── feature/description + ├── bugfix/issue-number + └── hotfix/issue-number +``` + +#### Creating Feature Branches + +```bash +# Update main/develop +git checkout develop +git pull origin develop + +# Create feature branch +git checkout -b feature/ISSUE-NUMBER-description + +# For specific module +cd falah-os +git checkout -b feature/ISSUE-NUMBER-description +git push origin feature/ISSUE-NUMBER-description +``` + +#### Working with Submodules + +```bash +# Navigate to specific module +cd falah-os-admin + +# Create and checkout feature branch +git checkout -b feature/new-feature + +# Make changes and commit +git add . +git commit -m "feat: add new feature" + +# Push changes +git push origin feature/new-feature + +# Go back to master repo +cd .. + +# Update submodule reference (if needed) +git add falah-os-admin +git commit -m "chore: update falah-os-admin submodule" +git push origin feature/ISSUE-NUMBER +``` + +### Phase 3: Testing + +#### Unit Testing + +```bash +# Run tests in specific module +cd +npm test # For Node.js projects +pytest # For Python projects +go test ./... # For Go projects +``` + +#### Integration Testing + +```bash +# Use mock networks for integration testing +cd falah-os-mocknet +# Follow module-specific test documentation +``` + +#### Staging Deployment + +- Deploy to staging environment +- Run end-to-end tests +- Validate across all modules + +### Phase 4: Code Review & Quality + +#### Pull Request Checklist + +- [ ] Feature branch created from `develop` +- [ ] All tests pass locally +- [ ] Code follows project style guide +- [ ] Documentation updated +- [ ] No breaking changes +- [ ] Linked to relevant GitHub issues + +#### Review Requirements + +- Minimum 2 approvals required +- CI/CD pipeline passes +- No merge conflicts +- Code coverage maintained + +### Phase 5: Deployment + +#### Staging Release + +```bash +# Create release branch +git checkout -b release/v1.x.x develop + +# Update version numbers and documentation +# Test thoroughly + +# Create PR to main +# After approval and merge, tag the release +git tag -a v1.x.x -m "Release version 1.x.x" +git push origin v1.x.x +``` + +#### Production Deployment + +- Merge `release/v1.x.x` to `main` +- Tag with version number +- Deploy to production +- Update all submodules references if needed + +--- + +## 📝 Documentation Standards + +### Commit Message Format + +``` +(): + + + +