From 1df51da55fa266fcf908b7ceba837bd59de3ca32 Mon Sep 17 00:00:00 2001
From: Olzhas Shaikenov <olzhas.shaikenov@gmail.com>
Date: Thu, 26 Mar 2026 16:17:24 -0400
Subject: [PATCH] docs

---
 CONTRIBUTING.md | 38 ++++++++++++++++++++++++++++++++++++++
 README.md       |  4 ++++
 2 files changed, 42 insertions(+)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..8994392
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,38 @@
+# Contributing
+
+Thank you for your interest in improving this project. Behavior, API, and configuration are documented in [README.md](README.md).
+
+## Development setup
+
+- Install **Go** using the version in [go.mod](go.mod).
+- For local runs that actually render PDFs (not required for tests), install Chrome or Chromium and set `CHROME_PATH` if it is not discovered automatically—see the README **Configuration** section.
+
+## Checks before opening a pull request
+
+These mirror [`.github/workflows/ci-cd.yml`](.github/workflows/ci-cd.yml):
+
+```bash
+gofmt -l src
+test -z "$(gofmt -l src)"
+```
+
+Use `gofmt -w src` to fix formatting. Then:
+
+```bash
+go test ./...
+go build ./src/cmd/document-service
+```
+
+The test suite mocks PDF generation, so you do not need Chromium to run `go test ./...`.
+
+## Pull requests
+
+- Keep changes focused on a single concern when possible.
+- Add or update tests when you change behavior.
+- Briefly describe what changed and why.
+
+## Security
+
+If you find a security vulnerability, please report it privately to the maintainers instead of opening a public issue.
+
+Pull requests run a Trivy filesystem scan (report-only) and the repository may use additional static analysis (for example CodeQL); fixing findings is appreciated when they are actionable.
diff --git a/README.md b/README.md
index 15bca91..96a574d 100644
--- a/README.md
+++ b/README.md
@@ -168,6 +168,10 @@ GitHub Actions workflow: [`.github/workflows/ci-cd.yml`](.github/workflows/ci-cd
 └── README.md
 ```
 
+## Future improvements
+
+- **gRPC API** — The HTTP surface stays ideal for curl, browsers, and typical ingress. A **gRPC** service would suit internal callers: typed request/response messages (for example HTML or XML as `bytes` and PDF as `bytes`), HTTP/2, and standard metadata for auth and tracing. Unary RPCs could match today’s model; streaming could help if much larger payloads are allowed later. Keeping HTTP while adding gRPC (or exposing HTTP via grpc-gateway) would be additive rather than replacing the current API.
+
 ## License
 
 Add a `LICENSE` file if you intend to open-source this repository.