# BBeOS Project Structure

This document provides a comprehensive overview of the BBeOS project structure and organization.

## 📁 Directory Layout

```
BBeOS/
├── 📚 docs/                          # Documentation
│   ├── 📋 phases/                    # Phase-by-phase development docs
│   │   ├── PHASE_1_*.md             # Research & Feasibility
│   │   ├── PHASE_2_*.md             # Bootstrapping
│   │   ├── PHASE_3_*.md             # Hardware Support
│   │   ├── PHASE_4_*.md             # User Interface
│   │   ├── PHASE_5_*.md             # Telephony Stack
│   │   ├── PHASE_6_*.md             # Packaging & Updates
│   │   └── PHASE_7_*.md             # Community & SDK
│   ├── 📖 guides/                    # How-to guides and tutorials
│   │   ├── EMULATION_GUIDE.md       # QEMU emulation guide
│   │   └── hardware-testing-guide.md # Hardware testing guide
│   ├── 🔧 api/                       # API documentation and design docs
│   │   ├── UI_UX_DESIGN.md          # UI/UX design specifications
│   │   └── SECURITY_ANALYSIS.md     # Security analysis and recommendations
│   └── DEVELOPMENT_GUIDE.md         # Main development guide
│
├── 💻 src/                           # Source code
│   ├── 🖥️ kernel/                    # Kernel configuration and patches
│   │   └── msm8960-defconfig        # MSM8960 kernel configuration
│   ├── 🔌 drivers/                   # Hardware drivers
│   │   ├── display/                  # Display drivers
│   │   │   └── q20-panel.c          # Q20 LCD panel driver
│   │   ├── input/                    # Input device drivers
│   │   │   └── q20-keyboard.c       # Q20 keyboard driver
│   │   └── Makefile                 # Driver build configuration
│   ├── 🖼️ ui/                        # User interface components
│   │   ├── compositor/              # Wayland compositor
│   │   │   └── q20-compositor.c     # Q20-specific compositor
│   │   ├── applications/            # UI applications
│   │   │   └── home-screen.c        # Home screen application
│   │   └── Makefile                 # UI build configuration
│   ├── 📞 telephony/                 # Phone functionality
│   │   ├── modem/                   # Modem drivers
│   │   │   └── q20-modem.c          # MDM9615 modem driver
│   │   ├── voice/                   # Voice call management
│   │   │   └── q20-voice.c          # Voice call driver
│   │   ├── sms/                     # SMS management
│   │   │   └── q20-sms.c            # SMS driver
│   │   └── Makefile                 # Telephony build configuration
│   ├── 📱 apps/                      # Core applications
│   │   ├── core/                    # Core system apps
│   │   │   ├── calculator.c         # Calculator application
│   │   │   └── text-editor.c        # Text editor application
│   │   └── Makefile                 # Application build configuration
│   ├── 🛠️ sdk/                       # Development tools and SDK
│   │   └── tools/                   # SDK tools
│   │       └── bbeos-sdk.c          # BBeOS SDK main tool
│   └── 📦 packaging/                 # System packaging and deployment
│       ├── system/                  # System image creation
│       │   └── image-builder.c      # System image builder
│       ├── security/                # Security components
│       │   └── secure-boot.c        # Secure boot implementation
│       ├── updates/                 # Update system
│       │   └── ota-updater.c        # OTA update system
│       └── Makefile                 # Packaging build configuration
│
├── 🔨 build/                         # Build artifacts
│   ├── 🖥️ kernel/                    # Kernel builds
│   │   ├── zImage                   # Kernel image
│   │   ├── *.dtb                    # Device tree blobs
│   │   └── modules/                 # Kernel modules
│   ├── 📁 rootfs/                    # Root filesystem
│   │   ├── bin/                     # Binary files
│   │   ├── etc/                     # Configuration files
│   │   ├── lib/                     # Library files
│   │   └── init                     # Init script
│   ├── 🖼️ images/                    # Boot images
│   │   ├── bbeos-boot.img           # Bootable system image
│   │   ├── initramfs.img            # Initial RAM filesystem
│   │   └── recovery.img             # Recovery image
│   ├── 🖼️ ui/                        # UI build artifacts
│   │   ├── compositor/              # Compiled compositor
│   │   ├── applications/            # Compiled applications
│   │   └── assets/                  # UI assets
│   └── 📦 boot-unpacked/             # Unpacked boot components
│
├── 🔧 scripts/                       # Build automation and tools
│   ├── build-kernel.sh              # Full kernel build script
│   ├── build-kernel-minimal.sh      # Minimal kernel build script
│   ├── build-rootfs.sh              # Root filesystem build script
│   ├── build-boot-image.sh          # Boot image creation script
│   ├── build-drivers.sh             # Driver build script
│   ├── build-ui.sh                  # UI build script
│   ├── build-telephony.sh           # Telephony build script
│   ├── build-packaging.sh           # Packaging build script
│   ├── emulate-simple.sh            # Simple QEMU emulation
│   ├── emulate-bbeos.sh             # Full BBeOS emulation
│   ├── emulate-terminal.sh          # Terminal-based simulation
│   ├── hardware-test.sh             # Hardware testing script
│   ├── flash-boot.sh                # Device flashing script
│   ├── test-qemu.sh                 # QEMU testing script
│   └── test-qemu-compatible.sh      # Compatible QEMU testing
│
├── 🧪 tests/                         # Test files and test automation
│   ├── unit/                        # Unit tests
│   ├── integration/                 # Integration tests
│   └── hardware/                    # Hardware tests
│
├── 📦 vendor/                        # Third-party code and dependencies
│   └── kernel-source/               # Linux kernel source
│       ├── arch/arm/boot/dts/qcom/  # Qualcomm device trees
│       └── ...                      # Other kernel files
│
├── 📥 downloads/                     # External downloads and sources
│   ├── busybox-1.36.1/              # BusyBox source
│   ├── busybox-1.36.1.tar.bz2       # BusyBox archive
│   └── ...                          # Other downloads
│
├── 🌐 community/                     # Community website and resources
│   └── website/                     # Community website
│       └── index.html               # Main website page
│
├── 🔬 research/                      # Hardware research and analysis
│   ├── q20-hardware-research.md     # Q20 hardware research
│   ├── bootloader-analysis.md       # Bootloader analysis
│   ├── driver-compatibility.md      # Driver compatibility research
│   └── q20-specs.md                 # Q20 specifications
│
├── 📋 .gitea/                        # Gitea configuration
│   └── workflows/                   # CI/CD workflows
│       └── ci.yml                   # Continuous integration
│
├── 📄 Configuration Files
│   ├── README.md                    # Project overview
│   ├── QUICK_START.md               # Quick start guide
│   ├── PROJECT_STRUCTURE.md         # This file
│   ├── .gitignore                   # Git ignore rules
│   ├── config.yaml                  # Gitea runner configuration
│   └── bbeos-runner.service         # Systemd service file
│
└── 🏗️ hardware/                     # Hardware specifications
    └── q20-specs.md                 # BlackBerry Classic Q20 specs
```

## 🎯 Organization Principles

### **1. Separation of Concerns**
- **Source code** (`src/`) is separate from **build artifacts** (`build/`)
- **Documentation** (`docs/`) is organized by type and purpose
- **Scripts** (`scripts/`) handle automation and tooling
- **Third-party code** (`vendor/`) is isolated from project code

### **2. Build System Organization**
- **Build artifacts** are placed in `build/` subdirectories
- **Downloads** are stored in `downloads/` directory
- **Scripts** reference the new directory structure
- **Clean separation** between source and build files

### **3. Documentation Structure**
- **Phase documentation** in `docs/phases/`
- **How-to guides** in `docs/guides/`
- **API documentation** in `docs/api/`
- **Main development guide** at `docs/DEVELOPMENT_GUIDE.md`

### **4. Source Code Organization**
- **Kernel components** in `src/kernel/`
- **Hardware drivers** in `src/drivers/`
- **User interface** in `src/ui/`
- **Telephony stack** in `src/telephony/`
- **Applications** in `src/apps/`
- **Development tools** in `src/sdk/`
- **Packaging tools** in `src/packaging/`

## 🔄 Build Workflow

### **1. Kernel Build**
```bash
./scripts/build-kernel.sh          # Full kernel build
./scripts/build-kernel-minimal.sh  # Minimal kernel build
```
- **Source**: `vendor/kernel-source/`
- **Output**: `build/kernel/`

### **2. Root Filesystem**
```bash
./scripts/build-rootfs.sh          # Build BusyBox rootfs
```
- **Source**: `downloads/busybox-*/`
- **Output**: `build/rootfs/`

### **3. System Components**
```bash
./scripts/build-drivers.sh         # Build hardware drivers
./scripts/build-ui.sh              # Build UI components
./scripts/build-telephony.sh       # Build telephony stack
./scripts/build-packaging.sh       # Build system images
```
- **Source**: `src/*/`
- **Output**: `build/*/`

### **4. System Integration**
```bash
./scripts/build-boot-image.sh      # Create bootable image
```
- **Input**: `build/kernel/`, `build/rootfs/`
- **Output**: `build/images/`

## 🧪 Testing and Emulation

### **Emulation Options**
```bash
./scripts/emulate-simple.sh        # Simple QEMU demo
./scripts/emulate-bbeos.sh         # Full BBeOS emulation
./scripts/emulate-terminal.sh      # Terminal-based simulation
```

### **Hardware Testing**
```bash
./scripts/hardware-test.sh         # Hardware component testing
```

## 📚 Documentation Access

### **Main Guides**
- **Development Guide**: `docs/DEVELOPMENT_GUIDE.md`
- **Project Structure**: `PROJECT_STRUCTURE.md` (this file)
- **Quick Start**: `QUICK_START.md`

### **Phase Documentation**
- **Phase 1**: `docs/phases/PHASE_1_*.md` - Research & Feasibility
- **Phase 2**: `docs/phases/PHASE_2_*.md` - Bootstrapping
- **Phase 3**: `docs/phases/PHASE_3_*.md` - Hardware Support
- **Phase 4**: `docs/phases/PHASE_4_*.md` - User Interface
- **Phase 5**: `docs/phases/PHASE_5_*.md` - Telephony Stack
- **Phase 6**: `docs/phases/PHASE_6_*.md` - Packaging & Updates
- **Phase 7**: `docs/phases/PHASE_7_*.md` - Community & SDK

### **How-to Guides**
- **Emulation**: `docs/guides/EMULATION_GUIDE.md`
- **Hardware Testing**: `docs/guides/hardware-testing-guide.md`

### **API Documentation**
- **UI/UX Design**: `docs/api/UI_UX_DESIGN.md`
- **Security Analysis**: `docs/api/SECURITY_ANALYSIS.md`

## 🔧 Configuration

### **Build Configuration**
- **Kernel config**: `src/kernel/msm8960-defconfig`
- **Device tree**: `vendor/kernel-source/arch/arm/boot/dts/qcom/`
- **Build artifacts**: `build/` directory structure

### **Environment Variables**
- `CROSS_COMPILE`: ARM cross-compilation toolchain
- `KERNEL_DIR`: Kernel source directory (`vendor/kernel-source`)
- `BUILD_DIR`: Build output directory (`build/`)

## 🎯 Benefits of This Structure

### **1. Maintainability**
- **Clear separation** between source, build, and documentation
- **Consistent naming** conventions throughout
- **Modular organization** for easy navigation

### **2. Scalability**
- **Extensible structure** for new components
- **Standard directories** for common project needs
- **Build system** that scales with project growth

### **3. Developer Experience**
- **Intuitive navigation** through logical organization
- **Comprehensive documentation** at every level
- **Clear build workflows** with dedicated scripts

### **4. Open Source Best Practices**
- **Standard directory layout** following open source conventions
- **Proper separation** of concerns
- **Comprehensive documentation** structure

---

*This structure is designed to support the development of a complete operating system while maintaining clarity and organization for developers and contributors.*