# 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 <module-name>
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

```
<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

```markdown
## 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:

1. **Overview**: What the module does
2. **Installation**: How to set it up
3. **Quick Start**: Basic usage example
4. **API Documentation**: For libraries/SDKs
5. **Configuration**: Setup and environment variables
6. **Testing**: How to run tests
7. **Contributing**: Contribution guidelines
8. **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

1. **Development Phase** (2-4 weeks)
   - Features merged to `develop`
   - Daily integration testing

2. **Release Candidate Phase** (1 week)
   - Release branch created: `release/v1.x.x`
   - Bug fixes only
   - Release notes prepared

3. **Production Release**
   - Merge to `main`
   - Tag release: `git tag -a v1.x.x`
   - Update all dependent modules

---

## 🛠️ Common Tasks

### Sync All Submodules with Remote

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

### Check Submodule Status

```bash
git submodule status
```

### Add New Submodule

```bash
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

```bash
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

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

### During Development

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

### Before Creating PR

1. Run all tests locally
2. Update CHANGELOG.md
3. Verify no conflicts
4. Add meaningful PR description
5. 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:

1. **GitHub Issues**: Create an issue in the relevant module repository
2. **Discussions**: Use GitHub Discussions for general questions
3. **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