docs: rewrite ARCHITECTURE.md, README.md; add CHANGELOG and CONTRIBUTING

- ARCHITECTURE.md: all modules, Helm charts, billing/lifecycle flow, WordPress - README.md: updated features, API endpoints, configuration, project structure - CHANGELOG.md: full changelog for all unreleased changes - CONTRIBUTING.md: commit conventions, documentation requirements, PR checklist
2026-04-22 16:45:30 +03:30
parent e10f9c5235
commit 5f77c07183
4 changed files with 538 additions and 284 deletions
@@ -0,0 +1,145 @@
+# Contributing to CloudHost
+
+## Commit Conventions
+
+This project follows [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
+
+### Format
+
+```
+<type>(<scope>): <short description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### Types
+
+| Type | When to use |
+|------|-------------|
+| `feat` | New feature or capability |
+| `fix` | Bug fix |
+| `refactor` | Code change that neither fixes a bug nor adds a feature |
+| `docs` | Documentation only changes |
+| `test` | Adding or updating tests |
+| `chore` | Build process, CI, dependency updates |
+| `perf` | Performance improvement |
+| `style` | Code style (formatting, semicolons, etc.) |
+
+### Scopes
+
+| Scope | Area |
+|-------|------|
+| `build` | Build service, Kaniko, Dockerfile generation |
+| `helm` | Helm chart templates and values |
+| `k8s` | Kubernetes service, cluster management |
+| `billing` | Wallet, transactions, plans |
+| `lifecycle` | Auto-suspend/delete scanner |
+| `auth` | Authentication, JWT, guards |
+| `apps` | Applications module |
+| `deploy` | Deployments module |
+| `frontend` | Next.js frontend |
+| `docs` | Documentation files |
+| `deps` | Dependency changes |
+
+### Examples
+
+```
+feat(helm): add WordPress wp-content PVC template
+fix(build): detect runtime from parent dir not zip file
+feat(lifecycle): add cron-based app suspension scanner
+docs: update ARCHITECTURE.md with billing flow
+test(k8s): add buildHelmValues unit tests
+refactor(billing): extract calculateCostForApp method
+```
+
+---
+
+## Documentation Requirements
+
+### When to Update Docs
+
+Every change **must** include documentation updates where applicable:
+
+1. **New module/service** → Update `ARCHITECTURE.md` module table + project structure
+2. **New API endpoint** → Update `README.md` API endpoints section
+3. **New env variable** → Update `README.md` configuration table + `configuration.ts`
+4. **New Helm template** → Update `ARCHITECTURE.md` Helm chart table
+5. **Breaking change** → Add `BREAKING CHANGE:` footer in commit + update CHANGELOG
+
+### CHANGELOG
+
+Update `CHANGELOG.md` under `[Unreleased]` for every PR:
+
+- **Added** — new features
+- **Changed** — changes to existing functionality
+- **Deprecated** — soon-to-be removed features
+- **Removed** — removed features
+- **Fixed** — bug fixes
+- **Security** — vulnerability fixes
+
+---
+
+## Development Workflow
+
+### Branch Strategy
+
+```
+main              ← production-ready
+  └── feat/*      ← feature branches
+  └── fix/*       ← bug fix branches
+  └── refactor/*  ← refactoring branches
+```
+
+### PR Checklist
+
+Before submitting a PR:
+
+- [ ] Code compiles: `cd backend && npx tsc --noEmit`
+- [ ] Frontend compiles: `cd frontend && npx tsc --noEmit`
+- [ ] Helm chart lints: `helm lint backend/helm/cloudhost-app`
+- [ ] Tests pass: `cd backend && npm test`
+- [ ] CHANGELOG.md updated
+- [ ] Documentation updated (if applicable)
+- [ ] No `console.log` left in production code (use `Logger` service)
+
+### Code Style
+
+- **TypeScript strict mode** — no `any` unless explicitly justified
+- **NestJS patterns** — use decorators, dependency injection, modules
+- **Logging** — use NestJS `Logger` service, not `console.log`
+- **Error handling** — use NestJS exceptions (`NotFoundException`, `BadRequestException`, etc.)
+- **Naming** — `camelCase` for variables/methods, `PascalCase` for classes/types, `kebab-case` for files
+
+---
+
+## Testing
+
+### Unit Tests
+
+```bash
+cd backend && npm test
+```
+
+Tests are co-located with source files (`*.spec.ts`):
+
+| Test file | Coverage |
+|-----------|----------|
+| `build.service.spec.ts` | WordPress Dockerfile, runtime detection, PVC cleanup |
+| `helm.service.spec.ts` | Chart path resolution, temp file management |
+| `kubernetes.service.spec.ts` | Helm values building, password generation |
+| `clusters.service.spec.ts` | Default cluster selection, delete/reassign |
+
+### Validation
+
+```bash
+# Backend TypeScript
+cd backend && npx tsc --noEmit
+
+# Frontend TypeScript
+cd frontend && npx tsc --noEmit
+
+# Helm chart
+helm lint backend/helm/cloudhost-app
+```