BBeOS/PROJECT_STRUCTURE.md

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

./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

./scripts/build-rootfs.sh          # Build BusyBox rootfs

• Source: downloads/busybox-*/
• Output: build/rootfs/

3. System Components

./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

./scripts/build-boot-image.sh      # Create bootable image

• Input: build/kernel/, build/rootfs/
• Output: build/images/

🧪 Testing and Emulation

Emulation Options

./scripts/emulate-simple.sh        # Simple QEMU demo
./scripts/emulate-bbeos.sh         # Full BBeOS emulation
./scripts/emulate-terminal.sh      # Terminal-based simulation

Hardware Testing

./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.