docs: add project documentation

CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+All notable project changes should be documented here.
+
+This project has not yet established a versioned changelog. Add entries as releases are published.
+
+## Unreleased
+
+- Documentation structure established.

CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing
+
+Thank you for your interest in improving htop-web.
+
+## Before making changes
+
+1. Review the README and relevant documentation.
+2. Check the existing implementation before introducing new dependencies or changing behavior.
+3. Keep changes focused on a clear issue or improvement.
+
+## Development workflow
+
+1. Create a branch for your change.
+2. Implement and test the change.
+3. Run the backend Gradle build from `backend/`:
+
+   ```bash
+   ./gradlew clean build
+   ```
+
+4. Review the Git diff and ensure generated files, credentials, and local configuration are not included.
+5. Update documentation when necessary.
+6. Submit your changes with a clear description of the problem and solution.
+
+## Code quality
+
+- Follow the conventions already used in the relevant module.
+- Avoid unrelated refactoring.
+- Do not claim support for monitoring capabilities that have not been tested in the target environment.
+- Never commit passwords, tokens, private keys, or production secrets.
+
+## Reporting issues
+
+Include the steps to reproduce the issue, expected behavior, actual behavior, relevant logs, and environment details. Remove sensitive information from logs before sharing them.

docs/ARCHITECTURE.md

@@ -0,0 +1,44 @@
+# Architecture
+
+## Overview
+
+htop-web is designed as a single deployable application containing an Angular frontend and a Spring Boot backend.
+
+```text
+Web browser
+    |
+    | HTTP
+    v
+Spring Boot application
+    |
+    +-- Angular production assets
+    |
+    +-- WebFlux REST controllers
+    |
+    +-- System information services
+             |
+             +-- OSHI
+             +-- Operating-system information
+```
+
+## Frontend
+
+The frontend is implemented with Angular and TypeScript. Its source code is located in `frontend/src/`.
+
+The production build is generated during the Gradle build and copied into the backend's static resources.
+
+## Backend
+
+The backend uses Java, Spring Boot and Spring WebFlux. Backend source code is located in `backend/src/main/java/com/htopweb/`.
+
+Controllers expose system information to the frontend, while service classes collect and prepare the relevant data.
+
+## System information
+
+OSHI is used to obtain operating-system and hardware information. The data available depends on the runtime environment and permissions.
+
+## Packaging
+
+The Gradle build combines the frontend production assets with the Spring Boot application. Docker packages the resulting JAR into a single application container.
+
+See the root `Dockerfile` and `docker-compose.yml` for the current container setup.

docs/CONFIGURATION.md

@@ -0,0 +1,28 @@
+# Configuration
+
+## Docker Compose
+
+The root `docker-compose.yml` defines the application container.
+
+Default port mapping:
+
+- Host: `8088`
+- Container: `8080`
+
+Change the port mapping in `docker-compose.yml` if host port `8088` is already in use.
+
+## Application settings
+
+The Spring Boot configuration is maintained in:
+
+`backend/src/main/resources/application.yaml`
+
+Review the actual configuration file before changing application properties. This document intentionally does not assume environment variables or settings that may not exist in the current implementation.
+
+## Container permissions and monitoring scope
+
+System metrics available to the application depend on the operating system, container runtime, mounted filesystems, and granted permissions.
+
+A container does not automatically have complete visibility into its host. Docker Desktop on Windows runs Linux containers in a virtualized Linux environment, so reported metrics may describe that environment rather than Windows itself.
+
+Do not expose the monitoring interface to untrusted networks without appropriate access controls and network security.

docs/DEVELOPMENT.md

@@ -0,0 +1,54 @@
+# Development
+
+## Prerequisites
+
+- Java 21
+- Node.js and npm compatible with `frontend/package.json`
+- Docker Engine and Docker Compose for container testing
+
+## Build and test
+
+From the repository root:
+
+```bash
+cd backend
+./gradlew clean build
+```
+
+This invokes the configured Gradle build, including frontend build tasks.
+
+## Frontend development
+
+Frontend source code is located in `frontend/`.
+
+Install dependencies using the lockfile:
+
+```bash
+cd frontend
+npm ci
+```
+
+Run the frontend development server using the project's configured npm scripts:
+
+```bash
+npm start
+```
+
+If the project does not define a `start` script, inspect `frontend/package.json` and use its available script, such as `npm run`.
+
+## Run the container
+
+From the repository root, after a successful build:
+
+```bash
+docker compose up -d --build
+docker compose logs -f htop-web
+```
+
+## Contribution guidelines
+
+- Keep changes focused and reviewable.
+- Do not commit generated build output or dependency directories.
+- Do not commit credentials, private keys, or local environment files.
+- Update documentation when build or runtime behavior changes.
+- Run the build before submitting changes.

docs/INSTALLATION.md

@@ -0,0 +1,42 @@
+# Installation
+
+## Requirements
+
+- Docker Engine
+- Docker Compose
+- Java 21 and Node.js/npm if building the application locally
+
+## Build the application
+
+From the repository root:
+
+```bash
+cd backend
+./gradlew clean build
+cd ..
+```
+
+The Gradle build also builds the Angular frontend and packages its production assets into the Spring Boot application.
+
+## Start with Docker Compose
+
+```bash
+docker compose up -d --build
+```
+
+The default Compose configuration maps host port `8088` to container port `8080`.
+
+Open http://localhost:8088 in your browser.
+
+## Check status and logs
+
+```bash
+docker compose ps
+docker compose logs -f htop-web
+```
+
+## Stop the application
+
+```bash
+docker compose down
+```