Skip to content

ROADMAP.md

Latest commit

 

History

History
240 lines (175 loc) · 7.22 KB

ROADMAP.md

File metadata and controls

240 lines (175 loc) · 7.22 KB
Raw

Lux Roadmap

Long-term vision: Build Lux into a puzzle-based learning platform that combines Linux, programming, cybersecurity, and AI-assisted learning with a modern cross-platform experience.

Roadmap status: the community milestone, sandbox hardening, and v1.0 release artifacts are complete. The current implementation centers on server.py and agent.py, with local JSON state and a Flutter/Dart path planned for mobile support.

If you want to work on a section of the roadmap Get my approval and format the branch like this: <username>/<scope>/<feature>

Development

Create and activate a virtual environment, then install the application dependencies:

python -m venv venv
source venv/bin/activate
python -m pip install -r requirements.txt
python -m pip install -r requirements-dev.txt

Start the development server:

python server.py

The server listens on http://127.0.0.1:5050. Flask's development command can also be used:

export FLASK_APP=server.py
export FLASK_DEBUG=1
flask run --port 5050

Run the test suite and, when installed, lint the project:

pytest
ruff check .

Docker is required for script-based puzzle validation. Ollama is optional for AI hints.

Production

Copy .env.example to .env, replace all placeholder secrets, and start the container stack:

docker-compose up -d

The application is served by Gunicorn on port 5050. Check liveness and readiness with:

curl http://127.0.0.1:5050/health
curl http://127.0.0.1:5050/ready

Use .env.example as the configuration reference. LUX_DOCKER_RUNTIME=runsc enables gVisor where installed, and LUX_SANDBOX_AUDIT_LOG selects the JSONL audit destination. Single-instance deployments can use SQLite; PostgreSQL is recommended for hosted deployments. The current local-first code still stores progress in JSON, so database migrations and repository integration are required before enabling multi-user production persistence.

Before a public launch, complete authentication, password and token security, database migrations, TLS, rate limiting, upload limits, backups, monitoring, and authorization checks. See docs/DEPLOYMENT.md for the deployment checklist and Gunicorn configuration.

Core Platform

  • Flask puzzle server
  • CLI puzzle agent
  • Ollama-powered hints
  • Docker-based code validation
  • GitHub Actions CI
  • Security scanning (Bandit, CodeQL, Snyk)

Puzzle Content

Linux

  • Basic Linux command puzzles
  • File system navigation
  • Process management
  • Networking
  • Package management
  • Shell scripting
  • Permissions and ownership
  • Log analysis
  • System administration
  • Bash challenge levels

Programming

  • Basic C challenges
  • Intermediate C puzzles
  • Memory management challenges
  • Data structures
  • Algorithms
  • Python puzzles
  • Java puzzles
  • JavaScript puzzles

Cybersecurity

  • Web security puzzles
  • Reverse engineering
  • Digital forensics
  • Cryptography
  • Secure coding challenges
  • Beginner CTF-style levels

DevOps

  • Docker puzzles
  • Git challenges
  • CI/CD exercises
  • Cloud fundamentals

Current Puzzle Catalog

  • Linux command, scripting, and admin levels are implemented
  • Programming levels cover C, Python, Java, and JavaScript
  • Cybersecurity levels cover web security, reverse engineering, forensics, cryptography, secure coding, and beginner CTFs
  • DevOps levels cover Docker, Git, CI/CD, and cloud fundamentals
  • Each puzzle includes category, difficulty, and tags metadata for filtering

User Experience

CLI Improvements

  • Progress tracking in agent.py with per-level completion, streaks, and solved-history summaries
  • Achievement system with unlockable milestones and badge summaries tied to completed levels
  • Save/load progress using JSON state files so the CLI can restore solved levels and user state
  • Difficulty ratings from server.py surfaced in the CLI and used for puzzle ordering
  • Better hint generation in agent.py tuned to the current puzzle, progress, and prior attempts

Note: These CLI progress and achievement features are now implemented in the main codebase with backward-compatible state migration.

Web UI

  • Flask web frontend layered on top of server.py as the primary browser-based experience
  • Responsive design for desktop and mobile browsers
  • User profiles for saved progress, preferences, and personalization
  • Leaderboards for puzzle completion, streaks, and challenge performance
  • Puzzle browser with search, filters, categories, and difficulty views
  • Progress dashboard with completion, streak, and achievement summaries

Mobile App

  • Flutter/Dart prototype that reuses the same puzzle API exposed by server.py
  • Shared API backend for authentication, progress sync, puzzle delivery, and submissions
  • iOS support through the Flutter client
  • Android support through the Flutter client
  • Offline puzzle packs for limited-connectivity play
  • Push notifications for streaks, reminders, and new content

AI Features

  • Ollama hint generation
  • Adaptive hints based on progress and puzzle history in agent.py
  • Multiple AI models with a clear fallback order
  • Local model selection for privacy and offline use
  • Personalized learning paths based on strengths and gaps
  • Puzzle generation with AI for new practice content

Security & Sandboxing

Current

  • Docker execution
  • Resource limits
  • Network isolation

Planned

  • Stronger Docker restrictions for safer puzzle execution
  • Read/write isolation for ephemeral workspace access
  • gVisor support for a stronger runtime boundary
  • Firecracker support for microVM-based isolation
  • Secure execution auditing for traceable sandbox activity

See docs/FIRECRACKER.md for the microVM design and rollout criteria.

Testing

  • Smoke tests
  • API integration tests
  • Docker execution tests
  • Security tests
  • End-to-end testing

Open Source Community

  • Contributing guide
  • Issue templates
  • Pull request template
  • Contributor recognition system
  • Good first issue labels
  • Mentorship-friendly issues

Contributor data and starter issue guidance live in contributors.json, .github/labels.yml, and docs/MENTORSHIP_ISSUES.md.

Game Vision

Puzzle Adventure Mode

  • Story-driven progression
  • Unlockable worlds
  • Puzzle campaigns
  • Character progression
  • Achievement badges
  • Certain puzzles are certain building blocks to advance

Running / Puzzle Hybrid

  • Level builder
  • Real-world activity integration
  • Daily puzzle challenges
  • XP and leveling system
  • Streak tracking
  • Exploration-based gameplay
  • Mobile-first experience

Release Goals

v0.1

  • Stable CLI experience
  • 25+ puzzles
  • Improved testing

v0.5

  • Web UI
  • User accounts
  • 100+ puzzles

v1.0

  • Flutter mobile app
  • Story mode
  • Advanced sandboxing
  • Release artifacts: Dockerfile, Compose, deployment documentation, API documentation, /ready, and versioned submit endpoint
  • Public launch