[#4] Finalize backend bootstrap and docs structure

.github/pull_request_template.md

@@ -1,16 +1,37 @@
 ## Description
 
-Describe what this PR changes.
+- What changed?
+- Why was this change needed?
 
 ## Closes
 
-- Closes #XX
+Closes #XX
 
 ## Related
 
-- Relates to #YY
+Relates to #YY
+
+## Checklist
+
+- [ ] Code follows project conventions in `CONTRIBUTING.md`
+- [ ] Self-review completed
+- [ ] Tests added/updated where needed
+- [ ] Documentation updated where needed
 
 ## Testing
 
-List validation steps and test results.
+Steps to verify the change:
+
+```pwsh
+# Example
+cd backend
+mvn test
+```
+
+Additional checks (if applicable):
+
+```pwsh
+cd blockchain
+npm test
+```
 

.gitignore

@@ -25,3 +25,7 @@
 .DS_Store
 Thumbs.db
 
+# Python
+__pycache__/
+*.py[cod]
+

AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Project snapshot
 - Repository is in **bootstrap/planning stage**: infra + blockchain module are implemented; backend and frontend are mostly scaffolds.
-- Start context in `README.md`, `START_HERE.md`, `PROJECT_SUMMARY.md`.
+- Start context in `README.md`, `START_HERE.md`, `GITHUB_ISSUES_PLAN.md`, and `docs/ARCHITECTURE.md`.
 - Main folders: `backend/` (multi-module Maven), `blockchain/` (Hardhat), `deploy/` (local stack), `docs/` (CQRS/event-sourcing intent).
 
 ## Architecture and service boundaries
@@ -38,7 +38,7 @@
 - Git workflow conventions are documented and reused across docs:
   - branch: `feature/#XX-description`
   - commit: `[#XX] short message`
-  - PR text includes `Closes #XX` (`START_HERE.md`, `INDEX.md`).
+  - PR text includes `Closes #XX` (`START_HERE.md`, `CONTRIBUTING.md`).
 
 ## Integration points and dependencies
 - Event hash bridge: backend `event-store-service`/`audit-writer-service` should map DB `event_hash` to on-chain `AuditLedger.appendAuditRecord(...)`.
@@ -48,6 +48,6 @@
 
 ## Practical guidance for coding agents
 - Do not assume existing Spring/Angular app code; create minimal skeletons first when implementing new backend/frontend issues.
-- Align new code with the issue-driven plan documents (`GITHUB_ISSUES_PLAN.md`, `GITHUB_ISSUES_TEMPLATES.md`) because this repo is organized around those milestones.
+- Align new code with the issue-driven plan in `GITHUB_ISSUES_PLAN.md` because this repo is organized around those milestones.
 - When changing blockchain write paths, update tests in `blockchain/test/AuditLedger.test.js` in the same change.
 

CONTRIBUTING.md

@@ -0,0 +1,304 @@
+# Contributing to distributed-audit-ledger
+
+Thanks for contributing. This guide defines the project workflow and contribution standards.
+
+## Table of Contents
+
+- Development Environment Setup
+- Local Run Modes
+- Post-start Smoke Checks
+- Project Structure
+- Coding Standards
+- Branch Naming
+- Commit Messages
+- Pull Request Process
+- Testing
+- Docker Compose Quick Commands
+- Troubleshooting Quick Checks
+- Code Review Checklist
+
+---
+
+## Development Environment Setup
+
+### Prerequisites
+
+| Tool | Version |
+|------|---------|
+| Java (JDK) | 25+ |
+| Maven | 3.9+ |
+| Node.js | 20+ |
+| Docker Desktop | recent stable |
+| Git | 2.40+ |
+
+### First-time setup
+
+1. Clone repo and enter directory.
+2. Start local infrastructure from `deploy/`.
+3. Build backend modules.
+4. Compile and test blockchain module.
+
+PowerShell example:
+
+```pwsh
+Set-Location <repo-root>
+
+Set-Location deploy
+Copy-Item .env.example .env -ErrorAction SilentlyContinue
+docker compose up -d
+
+Set-Location ..\backend
+mvn clean compile -DskipTests
+
+Set-Location ..\blockchain
+npm install
+npm run compile
+npm test
+```
+
+---
+
+## Local Run Modes
+
+### Option A: Run services from source
+
+```pwsh
+Set-Location <repo-root>\deploy
+docker compose up -d
+
+Set-Location ..\backend\command-service
+mvn spring-boot:run
+```
+
+Run other services in separate terminals:
+
+```pwsh
+Set-Location <repo-root>\backend\event-store-service
+mvn spring-boot:run
+```
+
+```pwsh
+Set-Location <repo-root>\backend\audit-writer-service
+mvn spring-boot:run
+```
+
+```pwsh
+Set-Location <repo-root>\backend\query-service
+mvn spring-boot:run
+```
+
+### Option B: Validate modules only
+
+```pwsh
+Set-Location <repo-root>\backend
+mvn clean verify
+
+Set-Location ..\blockchain
+npm test
+```
+
+---
+
+## Post-start Smoke Checks
+
+```pwsh
+Invoke-WebRequest http://localhost:8081/actuator/health
+Invoke-WebRequest http://localhost:8082/actuator/health
+Invoke-WebRequest http://localhost:8083/actuator/health
+Invoke-WebRequest http://localhost:8084/actuator/health
+```
+
+Infra checks:
+
+```pwsh
+docker exec dal-kafka kafka-topics --bootstrap-server localhost:9092 --list
+```
+
+```pwsh
+Invoke-WebRequest http://localhost:8545 -Method Post -ContentType "application/json" -Body '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
+```
+
+---
+
+## Project Structure
+
+```text
+backend/
+|- common/
+|  |- event-model/
+|  `- shared-contracts/
+|- command-service/
+|- event-store-service/
+|- audit-writer-service/
+`- query-service/
+
+blockchain/
+|- contracts/
+|- scripts/
+`- test/
+
+deploy/
+|- docker-compose.yml
+`- init-db.sql
+
+docs/
+|- ARCHITECTURE.md
+|- CQRS_FLOW.md
+`- DEPLOYMENT.md
+```
+
+---
+
+## Coding Standards
+
+### General
+
+- Java 25.
+- Spring Boot 4.
+- WebFlux-first for backend HTTP APIs.
+- Keep controllers thin; business logic in services.
+
+### Reactive Conventions
+
+- Keep request path reactive end-to-end (`Mono`/`Flux`).
+- Avoid `.block()` in production code.
+- `.block()` is acceptable in tests for setup/assertions.
+- Do not call `subscribe()` in business request flow.
+
+### Contracts and Schema
+
+- Shared DTOs/events must live in `backend/common/*`.
+- Postgres schema is `audit` (explicit in SQL and mappings).
+- For blockchain write path changes, update `blockchain/test/AuditLedger.test.js` in the same change.
+
+---
+
+## Branch Naming
+
+Project convention:
+
+| Prefix | Purpose | Example |
+|--------|---------|---------|
+| `feature/` | Feature delivery | `feature/#6-event-store-consumer` |
+| `fix/` | Bug fix | `fix/#7-retry-logic` |
+| `docs/` | Documentation | `docs/#12-architecture-update` |
+| `test/` | Tests | `test/#8-query-filters` |
+
+Preferred pattern: `feature/#XX-description`.
+
+---
+
+## Commit Messages
+
+Project convention:
+
+```text
+[#XX] short message
+```
+
+Examples:
+
+```text
+[#4] Setup backend multi-module pom
+[#6] Add reactive Kafka consumer skeleton
+[#12] Update deployment docs
+```
+
+---
+
+## Pull Request Process
+
+1. Branch from `main`.
+2. Implement code and tests.
+3. Run local validation.
+4. Open PR with linked issue.
+5. Address review comments.
+
+PR description should include:
+
+```markdown
+## Description
+<what changed>
+
+## Closes
+Closes #XX
+
+## Related
+Relates to #YY
+```
+
+---
+
+## Testing
+
+Backend:
+
+```pwsh
+Set-Location <repo-root>\backend
+mvn test
+mvn verify
+```
+
+Blockchain:
+
+```pwsh
+Set-Location <repo-root>\blockchain
+npm test
+```
+
+Run a specific backend module:
+
+```pwsh
+Set-Location <repo-root>\backend
+mvn -pl command-service test
+```
+
+---
+
+## Docker Compose Quick Commands
+
+```pwsh
+Set-Location <repo-root>\deploy
+docker compose up -d
+docker compose ps
+docker compose logs -f
+docker compose down
+docker compose down -v
+```
+
+---
+
+## Troubleshooting Quick Checks
+
+### Kafka not reachable
+
+```pwsh
+docker compose -f <repo-root>\deploy\docker-compose.yml ps
+docker compose -f <repo-root>\deploy\docker-compose.yml logs kafka
+```
+
+### Postgres schema issues
+
+```pwsh
+docker compose -f <repo-root>\deploy\docker-compose.yml logs postgres
+```
+
+Verify table exists in `audit` schema (`audit.events`).
+
+### Ganache / contract issues
+
+```pwsh
+docker compose -f <repo-root>\deploy\docker-compose.yml logs ganache
+```
+
+---
+
+## Code Review Checklist
+
+- [ ] Issue scope is clear and linked in PR (`Closes #XX`).
+- [ ] Reactive flow preserved in backend request path.
+- [ ] Shared contracts/events updated in `backend/common/*` if needed.
+- [ ] Tests added or updated for behavior changes.
+- [ ] `mvn verify` (backend) and `npm test` (blockchain) pass locally.
+- [ ] Docs updated when architecture/workflow changed.
+