================================================================================ PAEON - PROJECT STRUCTURE SUMMARY
This document provides a quick reference for navigating the Paeon project. For detailed explanations, see PROJECT_STRUCTURE.md
README.md Main project overview, features, quick start LICENSE Apache 2.0 license text CMakeLists.txt Root build configuration (orchestrates all builds) CONTRIBUTING.md Developer contribution guidelines ROADMAP.md Future plans and feature roadmap BUILD_REQUIREMENTS.txt System dependencies checklist
📦 /docs/ Documentation (start here!) ├── ARCHITECTURE.md Deep-dive into system design ├── BUILDING.md Build instructions per OS ├── TUNING_GUIDE.md Optimization techniques ├── FAQ.md Common issues + solutions └── API_REFERENCE.md Doxygen-generated API docs
Purpose: Comprehensive user and developer documentation
💻 /core/ Native emulator engine (C++) ├── CMakeLists.txt Build config for core ├── include/ │ ├── emulator.h Main public API │ ├── vm_config.h VM configuration │ └── memory.h Memory management ├── src/ │ ├── emulator.cpp Lifecycle management │ ├── vm_manager.cpp Boot/shutdown logic │ ├── memory_optimizer.cpp RAM optimization (KSM, zswap) │ ├── cpu_scheduler.cpp CPU core binding │ ├── storage_handler.cpp Sparse image handling │ └── gpu/ │ ├── gpu_manager.cpp GPU abstraction │ ├── software_renderer.cpp SwiftShader integration │ └── gpu_memory_pool.cpp GPU memory management └── tests/ Unit tests for core ├── test_vm_manager.cpp ├── test_memory.cpp └── test_gpu.cpp
Purpose: THE HEART - Emulation engine, QEMU integration, optimization
🖼️ /launcher/ Desktop GUI (Electron + React) ├── package.json Node.js dependencies ├── main.js Main Electron process ├── preload.js IPC bridge to native ├── src/ │ ├── App.jsx Main React component │ ├── components/ │ │ ├── VMControl.jsx Start/Stop/Pause buttons │ │ ├── PerformanceMonitor.jsx Real-time graphs (CPU/RAM/GPU) │ │ ├── SettingsPanel.jsx Configuration UI │ │ └── Console.jsx Log viewer │ ├── utils/ │ │ ├── emulator_ipc.js Talks to native CLI │ │ ├── performance_tracker.js Metrics collection │ │ └── config_manager.js Config file handling │ └── styles/ CSS styling └── public/ └── index.html HTML entry point
Purpose: THE FACE - User-friendly GUI, real-time monitoring, controls
⚙️ /cli/ Command-line interface (C++)
├── CMakeLists.txt Build config
└── src/
├── main.cpp Entry point
├── commands/
│ ├── start_cmd.cpp paeon start
│ ├── stop_cmd.cpp paeon stop
│ ├── install_cmd.cpp paeon install app.apk
│ ├── config_cmd.cpp paeon config
│ └── logs_cmd.cpp paeon logs
└── utils/
├── argument_parser.cpp CLI flag parsing
└── output_formatter.cpp JSON/text output
Purpose: Command-line control, automation, CI/CD integration
🔌 /adb-bridge/ ADB integration (C++) ├── CMakeLists.txt └── src/ ├── adb_server.cpp Runs ADB daemon ├── adb_socket.cpp Socket communication ├── adb_commands.cpp Push/pull/install operations └── package_installer.cpp APK installation logic
Purpose: Communication with Android, app installation, file transfer
🤖 /system-image/ Minimal Android image builder (Python) ├── build_image.py Main image build script ├── config/ │ ├── minimal_packages.txt What to INCLUDE (minimal set) │ ├── removed_bloatware.txt What to EXCLUDE (Google bloat) │ └── selinux_policy.txt Simplified security policy ├── patches/ │ ├── disable_animations.patch Remove boot animations │ ├── reduce_heap_size.patch 512MB heap (vs. 2GB) │ ├── minimal_services.patch Disable unused services │ └── battery_optimization.patch Remove battery overhead └── tools/ ├── strip_bloat.sh Remove unused apps ├── compress_image.sh Create sparse qcow2 └── verify_size.sh Assert <800MB
Purpose: MINIMAL IMAGE - 800MB instead of 4-8GB, boot optimization
📦 /third_party/ External dependencies ├── qemu/ QEMU fork (ARM/x86 emulation) ├── angle/ OpenGL ES compatibility ├── swiftshader/ Software GPU renderer └── protobuf/ Protocol buffers
Purpose: Git submodules for core dependencies
📋 /config/ Configuration templates ├── schema.json JSON schema validation ├── defaults/ │ ├── low_end.json 512MB RAM, 1 vCPU preset │ ├── mid_range.json 1GB RAM, 2 vCPU preset │ └── high_end.json 2GB+ RAM, 4 vCPU preset └── examples/ └── custom_config.json User customization example
Purpose: Configuration templates and validation
🔨 /scripts/ Build automation ├── build.sh One-command build (handles all OSes) ├── test.sh Run all tests ├── benchmark.sh Performance benchmarks ├── format_code.sh Auto-format C++/JS ├── package.sh Create installers └── upload_release.sh Automate GitHub releases
Purpose: Developer workflow automation
📦 /installer/ Platform-specific installers ├── windows/ │ ├── nsis_installer.nsi .exe installer script │ ├── setup.ps1 PowerShell setup │ └── dependencies.txt Required Windows components ├── macos/ │ ├── create_dmg.sh DMG package creation │ ├── setup.sh macOS-specific setup │ └── dependencies.txt Homebrew deps ├── linux/ │ ├── setup.sh Universal Linux setup │ ├── ubuntu_setup.sh Ubuntu/Debian (apt) │ ├── fedora_setup.sh Fedora/RHEL (dnf) │ ├── arch_setup.sh Arch Linux (pacman) │ └── dependencies.txt Common Linux deps └── common/ ├── download_aosp.sh Clone AOSP source ├── validate_env.sh Check system requirements └── post_install.sh Post-installation setup
Purpose: Cross-platform installation experience (one-click, handled)
🧪 /tests/ Integration tests ├── integration_tests.cpp End-to-end tests (boot → install → run) ├── performance_benchmarks.cpp Startup time, memory profiling ├── compatibility_tests.cpp Different AOSP versions └── fixtures/ └── test_app.apk Sample app for testing
Purpose: Ensure everything works together
📊 /benchmarks/ Performance tracking ├── startup_time.csv Historical startup times ├── memory_usage.csv RAM usage over releases ├── cpu_profile.csv CPU utilization data └── generate_report.py Analyze and visualize trends
Purpose: Track performance over time, catch regressions
🤝 /community/ Community resources ├── ISSUE_TEMPLATES/ │ ├── bug_report.md Bug report template │ ├── feature_request.md Feature request template │ └── performance_issue.md Performance issue template └── PULL_REQUEST_TEMPLATE.md PR template
Purpose: Standardize issue/PR format
⚙️ /.github/workflows/ Continuous Integration (GitHub Actions) ├── build.yml Build on Windows/macOS/Linux ├── test.yml Run tests on every PR ├── release.yml Automated release builds └── benchmark.yml Performance regression testing
Purpose: Automated testing, builds, quality checks
CRITICAL FILES (Don't skip these): ├── CMakeLists.txt Master build configuration ├── core/include/emulator.h Public API every dev needs to know ├── docs/ARCHITECTURE.md Understand the design └── CONTRIBUTING.md How to contribute code
BUILD & TESTING: ├── scripts/build.sh How to compile ├── scripts/test.sh How to verify it works └── .github/workflows/ Automated CI
DOCUMENTATION: ├── README.md Project overview ├── docs/BUILDING.md Build instructions per OS ├── docs/TUNING_GUIDE.md Optimization techniques └── CONTRIBUTING.md How to contribute
CORE ENGINE: ├── core/ Native C++ emulation engine ├── adb-bridge/ Android communication └── system-image/ Minimal Android image
-
User runs: ./scripts/build.sh
-
Script does: ├─ Check dependencies ├─ Run cmake (generates build files) ├─ Compile core/ (C++) ├─ Compile cli/ (C++) ├─ Compile adb-bridge/ (C++) ├─ Install dependencies for launcher/ (npm) ├─ Build launcher/ (React + Electron) ├─ Run tests/ └─ Create installers/
-
Output in build/bin/: ├─ paeon-core (Native library) ├─ paeon-cli (CLI executable) └─ Paeon.exe/dmg/deb (Platform installer)
launcher/ (GUI) └─> cli/ (CLI) └─> core/ (Engine) └─> adb-bridge/ └─> third_party/ (QEMU, ANGLE, SwiftShader)
system-image/ └─> Build Minimal AOSP image (800MB)
Source code: ~15MB Build artifacts: ~500MB (temporary, deleted after install) Installed: ~1.5GB (including minimal Android image) Development setup: ~20GB (if building AOSP from scratch)
Step 1: Clone git clone https://github.com/yourusername/paeon.git cd paeon git submodule update --init --recursive
Step 2: Build ./scripts/build.sh
Step 3: Test ./scripts/test.sh
Step 4: Run ./build/bin/paeon-cli start --preset low_end OR ./launcher start
Step 5: Install APK ./build/bin/paeon-cli install ~/Downloads/myapp.apk
Step 6: Check logs ./build/bin/paeon-cli logs
================================================================================ WHERE TO CONTRIBUTE
If you want to...
🐛 Fix a bug → Look in: core/, cli/, adb-bridge/ (depending on component) → Add test in: tests/ → Reference issue in commit
✨ Add a feature → Create an issue first to discuss approach → Implement in appropriate directory → Add tests
📚 Improve docs → Edit: docs/*.md → Submit as PR
🎨 Improve GUI → Edit: launcher/src/ → Test on different screen sizes
🚀 Optimize performance → Benchmark first: ./scripts/benchmark.sh → Make change → Benchmark again, show improvements → Include before/after in PR
🔧 Fix a build issue → Edit: CMakeLists.txt or installer/ → Test on your OS → Include build output in PR
📊 Improve CI/testing → Edit: .github/workflows/ or tests/
See: docs/FAQ.md Ask: GitHub Issues or Discord Chat: https://discord.gg/paeon Mail: maintainers@paeon.io