docs: improve onboarding and contribution guide

CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing to GreenCode
+
+Thank you for contributing to GreenCode. The project supports environmental and
+sustainability workflows, so contributions should be clear, maintainable, and
+easy for new developers to verify.
+
+## Contribution Types
+
+Useful contributions include:
+
+- Bug fixes and feature enhancements.
+- Documentation improvements.
+- API examples and setup guidance.
+- UI/UX suggestions for future frontend work.
+- Governance and sustainability recommendations.
+- Tests that improve confidence in backend behavior.
+
+## Workflow
+
+1. Pick an existing issue or open one before making a large change.
+2. Fork the repository and create a branch from `main`.
+3. Use a descriptive branch name:
+   - `fix/user-validation`
+   - `feat/project-search`
+   - `docs/local-setup`
+4. Keep the change focused and reviewable.
+5. Link the issue in the pull request description using `Closes #123`.
+
+## Development Checklist
+
+Before opening a pull request:
+
+- Run `mvn test` when changing Java code.
+- Update docs when setup, APIs, or configuration behavior changes.
+- Avoid committing secrets, generated files, build output, or local `.env`
+  files.
+- Keep examples aligned with `env.example` and existing project structure.
+
+## Commit Style
+
+Use short, descriptive commit messages. Conventional prefixes are encouraged:
+
+- `docs: improve local setup guide`
+- `fix: validate project rating range`
+- `feat: add project search endpoint`
+- `test: cover user service validation`
+
+## Review Expectations
+
+Maintainers should be able to understand:
+
+- What changed.
+- Why the change is needed.
+- How it was tested.
+- Which issue the pull request resolves.
+
+Documentation-only pull requests should still include a brief testing note, such
+as confirming Markdown links and headings render correctly.

README.md

@@ -1,28 +1,96 @@
 # GreenCode
 
-GreenCode is an API core system designed to support esm_greencode .
-It consists of a **Spring Boot backend API** 
+GreenCode is a Spring Boot backend API for environmental and sustainability
+project management. It provides a foundation for tracking projects, users,
+configuration, deployment assets, and future integrations for environmental
+impact workflows.
 
----
+## Features
 
-## 🚀 Features
+- REST API built with Spring Boot.
+- JWT/OAuth-ready security dependencies.
+- PostgreSQL support for shared environments.
+- H2-friendly local development profile.
+- Centralized environment configuration through `env.example`.
+- Docker and Docker Compose assets for deployment.
+- Architecture, API, and deployment documentation under `docs/`.
 
-### Backend (Spring Boot)
-- RESTful API
-- JWT/OAuth authentication
-- PostgreSQL database support
-- Centralised configuration (`config/`, `.env`)
-- Dockerized for easy deployment
-- Swagger/OpenAPI documentation
+## Project Structure
 
-
-## 📁 Project Structure
+```text
 GreenCode/
-├── src/                 # Spring Boot source code
-├── config/              # external configuration & scripts
-├── docs/                # architecture, API docs
-├── greencode-frontend/  # React frontend (new)
+├── src/                 # Spring Boot source and tests
+├── config/              # External service configuration
+├── docs/                # Architecture, API, and deployment docs
+├── scripts/             # Setup, deployment, and backup scripts
 ├── pom.xml              # Maven build file
-└── docker-compose.yml   # Docker orchestration
+├── env.example          # Environment variable reference
+└── docker-compose.yml   # Local/deployment service orchestration
+```
+
+## Prerequisites
+
+- Java 17 or newer.
+- Maven 3.9 or newer.
+- Docker and Docker Compose for containerized setup.
+- PostgreSQL when running outside the default development profile.
+
+## Local Setup
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://github.com/bos-com/GreenCode.git
+   cd GreenCode
+   ```
+
+2. Copy the environment template:
+
+   ```bash
+   cp env.example .env
+   ```
+
+3. Review the values in `.env`, especially database, JWT, CORS, and logging
+   settings.
+
+4. Run the backend locally:
+
+   ```bash
+   mvn spring-boot:run
+   ```
+
+5. Run tests before opening a pull request:
+
+   ```bash
+   mvn test
+   ```
+
+## Docker Setup
+
+Use Docker Compose when you want the backend and supporting services to run in a
+repeatable local environment:
+
+```bash
+docker-compose up --build
+```
+
+Stop the stack with:
+
+```bash
+docker-compose down
+```
+
+## Documentation
+
+- API documentation: [`docs/api/README.md`](docs/api/README.md)
+- Architecture overview: [`docs/architecture/README.md`](docs/architecture/README.md)
+- Deployment guide: [`docs/deployment/README.md`](docs/deployment/README.md)
+
+## Contributing
+
+Start with [CONTRIBUTING.md](CONTRIBUTING.md) for branch naming, commit style,
+pull request expectations, and review guidance.
 
+## License
 
+This project is licensed under the terms in [LICENSE](LICENSE).