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

# 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

# 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

# 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

Issue Creation: Create GitHub issues for new features/bugs
Milestone Assignment: Assign to relevant milestones
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

# 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

# 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

# Run tests in specific module
cd <module-name>
npm test          # For Node.js projects
pytest            # For Python projects
go test ./...     # For Go projects

Integration Testing

# 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

# 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

<type>(<scope>): <subject>

<body>

<footer>

Types

feat: A new feature
fix: A bug fix
docs: Documentation only changes
style: Changes that don't affect code meaning
refactor: Code change that neither fixes a bug nor adds a feature
perf: Code change that improves performance
test: Adding or updating tests
chore: Changes to build process, dependencies, etc.

Example

feat(admin-dashboard): add user management panel

Implemented new user management interface in the admin panel
with the following features:
- User listing with pagination
- Create/Edit/Delete user operations
- Role assignment

Fixes #123

Pull Request Template

## Description
Provide a brief summary of the changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Related Issue
Closes #ISSUE_NUMBER

## Testing
Describe the tests run and results

## Screenshots (if applicable)
Add screenshots for UI changes

## Checklist
- [ ] My code follows the style guidelines
- [ ] I have performed a self-review
- [ ] I have commented complex areas
- [ ] I have updated documentation
- [ ] Tests pass locally
- [ ] No new warnings generated

Module README Requirements

Each module should include:

Overview: What the module does
Installation: How to set it up
Quick Start: Basic usage example
API Documentation: For libraries/SDKs
Configuration: Setup and environment variables
Testing: How to run tests
Contributing: Contribution guidelines
License: License information

🔄 Release Management

Versioning

All modules follow Semantic Versioning (SemVer): MAJOR.MINOR.PATCH

MAJOR: Breaking changes
MINOR: New features (backward compatible)
PATCH: Bug fixes (backward compatible)

Release Cycle

Development Phase (2-4 weeks)
- Features merged to develop
- Daily integration testing
Release Candidate Phase (1 week)
- Release branch created: release/v1.x.x
- Bug fixes only
- Release notes prepared
Production Release
- Merge to main
- Tag release: git tag -a v1.x.x
- Update all dependent modules

🛠️ Common Tasks

Sync All Submodules with Remote

git submodule foreach --recursive git fetch origin
git submodule foreach --recursive git pull origin main

Check Submodule Status

git submodule status

Add New Submodule

git submodule add https://github.com/maifors/new-module.git new-module
git add .gitmodules new-module
git commit -m "chore: add new-module submodule"
git push origin main

Remove a Submodule

git submodule deinit -f path/to/module
rm -rf .git/modules/path/to/module
git rm -f path/to/module
git commit -m "chore: remove module submodule"

📋 Module Dependency Map

falah-os (Core)
    ├── falah-os-sdk (SDK)
    │   ├── falah-os-app (App)
    │   ├── falah-os-admin (Admin)
    │   └── falah-os-istore (Store)
    ├── falah-os-sdk-py (Python SDK)
    ├── falah-os-ummahid (Identity)
    └── falah-os-ramz (Protocol)

Portals & Interfaces
    ├── ulp-portal (User Portal)
    ├── falah-os-dev-porta (Dev Portal)
    ├── falah-os-landing (Landing)
    └── falah-os-admin (Admin Portal)

Testing & Infrastructure
    ├── falah-os-mocknet (Mock Network)
    └── alah-os-mocknet (Alt Mock Network)

🤝 Contributing Guidelines

Before Starting

Check existing issues and PRs
Discuss major changes in issues first
Create branch from appropriate base (develop for features)
Keep commits atomic and well-documented

During Development

Write clean, well-commented code
Follow project code style
Add/update tests for changes
Update documentation
Keep branch up-to-date with base branch

Before Creating PR

Run all tests locally
Update CHANGELOG.md
Verify no conflicts
Add meaningful PR description
Link to relevant issues

📚 Additional Resources

Main Repository: https://github.com/Falah-Consultancy-Limited/Falah-OS-Master
GitHub Issues: Report bugs and request features
Project Board: Track development progress
Wiki: Additional documentation (if available)

✅ Checklist for New Team Members

Cloned repository with all submodules
Set up local development environment
Reviewed this README
Reviewed CONTRIBUTING.md in each module
Understood branching strategy
Set up IDE/editor with project standards
Ran tests successfully
Created first feature branch
Reviewed commit message standards
Understood release workflow

📞 Support & Contact

For questions or issues:

GitHub Issues: Create an issue in the relevant module repository
Discussions: Use GitHub Discussions for general questions
Team Communication: Reach out to the team lead

📄 License

This project and all submodules are licensed under the terms specified in each module's LICENSE file.

Last Updated: 2026-05-07
Maintained By: Falah Consultancy Limited
Repository: https://github.com/Falah-Consultancy-Limited/Falah-OS-Master