docs: add project roadmap and architecture decision records (closes #85)

docs/ROADMAP.md

@@ -0,0 +1,83 @@
+# BOS Project Roadmap
+
+This document outlines the development phases for BOS (Bugema Operating System),
+a free, open-source, self-hostable internet OS.
+
+## Vision
+
+BOS aims to provide a unified, browser-based operating system experience that
+individuals and organizations can host on their own infrastructure. It connects
+the broader Bugema Open Source Community (BOSC) ecosystem — including
+GreenCode, OpenCare-Core, and LifeLine-ICT — under a single platform.
+
+---
+
+## Phase 1: Documentation & Governance Foundations *(Current)*
+
+**Goal:** Establish the contributor experience and project governance so the
+community can grow sustainably.
+
+| Milestone                          | Status       |
+|------------------------------------|--------------|
+| Expand README with project overview | 🔄 In Progress |
+| Add CONTRIBUTING.md               | 🔄 In Progress |
+| Define Code of Conduct             | ⬜ Planned   |
+| Create issue and PR templates      | ⬜ Planned   |
+| Document architecture decisions    | 🔄 In Progress |
+| Choose and document license         | ✅ Done (MIT) |
+
+---
+
+## Phase 2: Core OS Abstractions & API Design
+
+**Goal:** Define the application model, file system abstraction, and user
+management APIs that form the kernel of BOS.
+
+| Milestone                                      | Status     |
+|------------------------------------------------|------------|
+| Design user authentication and session model   | ⬜ Planned |
+| Define virtual file system API                 | ⬜ Planned |
+| Create application manifest specification      | ⬜ Planned |
+| Build REST API for app lifecycle management    | ⬜ Planned |
+| Implement basic permission and role system     | ⬜ Planned |
+
+---
+
+## Phase 3: Application Ecosystem Integration
+
+**Goal:** Integrate BOSC projects as first-class BOS applications and enable
+third-party app development.
+
+| Milestone                                      | Status     |
+|------------------------------------------------|------------|
+| Package GreenCode as a BOS application         | ⬜ Planned |
+| Package OpenCare-Core as a BOS application     | ⬜ Planned |
+| Package LifeLine-ICT as a BOS application      | ⬜ Planned |
+| Create app developer SDK and documentation     | ⬜ Planned |
+| Build app marketplace / registry               | ⬜ Planned |
+
+---
+
+## Phase 4: Self-Hosting & Deployment Tooling
+
+**Goal:** Make BOS easy to deploy on personal servers, cloud VMs, or
+institutional infrastructure.
+
+| Milestone                                      | Status     |
+|------------------------------------------------|------------|
+| Docker Compose single-command deployment       | ⬜ Planned |
+| Automated backup and restore tooling           | ⬜ Planned |
+| HTTPS and reverse proxy configuration guide    | ⬜ Planned |
+| Resource monitoring and health dashboards      | ⬜ Planned |
+| Multi-tenant support                           | ⬜ Planned |
+
+---
+
+## How to Contribute
+
+Pick a milestone from the current phase and open an issue describing your
+proposed approach. See [CONTRIBUTING.md](../CONTRIBUTING.md) for workflow
+details.
+
+Significant design changes should be captured as Architecture Decision Records
+in `docs/adr/`.

docs/adr/001-mit-license.md

@@ -0,0 +1,46 @@
+# ADR-001: MIT License Selection
+
+## Status
+
+Accepted
+
+## Date
+
+2025-01-01
+
+## Context
+
+BOS is an educational and community-driven project created by the Bugema Open
+Source Community. The project needs a license that:
+
+- Allows free use, modification, and distribution
+- Is simple enough for student contributors to understand
+- Does not impose copyleft obligations that might discourage adoption by
+  institutions or companies
+- Is widely recognized and compatible with most other open-source licenses
+
+## Decision
+
+We chose the **MIT License** for BOS and its sub-projects.
+
+The MIT License is one of the most permissive open-source licenses. It imposes
+minimal restrictions — users must include the copyright notice and license text
+in copies — but otherwise allows commercial use, modification, distribution,
+and private use without restriction.
+
+## Consequences
+
+**Positive:**
+- Low barrier to adoption — anyone can use BOS without legal concerns
+- Compatible with virtually all other open-source licenses
+- Simple text that student contributors can read and understand
+- Widely used in the JavaScript, Python, and Java ecosystems the project
+  depends on
+
+**Trade-offs:**
+- No copyleft protection — third parties can create proprietary forks
+- No patent grant (unlike Apache 2.0)
+- Contributors' modifications can be closed-sourced by downstream users
+
+These trade-offs are acceptable for an educational project focused on community
+learning and collaboration.

docs/adr/002-documentation-first.md

@@ -0,0 +1,47 @@
+# ADR-002: Documentation-First Development Approach
+
+## Status
+
+Accepted
+
+## Date
+
+2025-01-15
+
+## Context
+
+BOS is in its early stages with a small contributor base of university students.
+The temptation is to jump directly into coding, but early-stage projects
+without documentation tend to accumulate technical debt and lose contributors
+who cannot understand the codebase.
+
+The Bugema Open Source Community (BOSC) uses its projects as learning platforms,
+so contributor onboarding is a primary concern.
+
+## Decision
+
+We adopt a **documentation-first development approach**: before implementing a
+feature, contributors must first document the design, API contracts, and
+expected behavior. Code PRs should be preceded (or accompanied) by
+documentation PRs.
+
+In practice this means:
+
+1. New features start as an issue describing the problem and proposed solution.
+2. An architecture decision record (ADR) is created for significant design
+   choices.
+3. API endpoints are documented before implementation begins.
+4. README and setup guides are updated as part of every feature PR.
+
+## Consequences
+
+**Positive:**
+- New contributors can understand the project without reading all the code
+- Design flaws are caught during documentation review, before code is written
+- The project builds a knowledge base that survives contributor turnover
+- Aligns with the educational mission of BOSC
+
+**Trade-offs:**
+- Slower initial velocity — writing docs before code takes more time upfront
+- Risk of documentation drift if docs are not updated alongside code changes
+- Requires discipline from all contributors, including reviewers

docs/adr/template.md

@@ -0,0 +1,28 @@
+# ADR Template
+
+Use this template when recording significant architectural decisions.
+
+## Title
+
+**ADR-NNN: [Short descriptive title]**
+
+## Status
+
+[Proposed | Accepted | Deprecated | Superseded by ADR-NNN]
+
+## Date
+
+YYYY-MM-DD
+
+## Context
+
+Describe the forces at play, the problem being solved, and any constraints.
+
+## Decision
+
+State the decision that was made and the rationale.
+
+## Consequences
+
+Describe the resulting context after applying the decision. Include both
+positive outcomes and trade-offs.