fix: improve README.md documentation structure and formatting #1428
Conversation
- Fix grammar error: 'host' to 'hosts' in repository description - Standardize section headers and improve consistency - Reorganize content with proper hierarchical structure - Improve formatting for better readability - Add numbered setup instructions for clarity - Standardize terminology (PostgreSQL, Docker, microservices) - Remove HTML line breaks and use proper markdown formatting - Add proper code block language specifications - Improve section organization and flow Fixes credebl#1275 Signed-off-by: DeepDn <[email protected]>
WalkthroughREADME.md was reorganized and rewritten: headings renamed and numbered, setup instructions restructured into stepwise commands (PostgreSQL, Prisma, seed, NATS, dependencies, env configuration, and microservice startup). No code or public API changes were made. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Assessment against linked issues
Poem
Pre-merge checks and finishing touches✅ Passed checks (5 passed)
✨ Finishing touches🧪 Generate unit tests
Tip 👮 Agentic pre-merge checks are now available in preview!Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.
Please see the documentation for more information. Example: reviews:
pre_merge_checks:
custom_checks:
- name: "Undocumented Breaking Changes"
mode: "warning"
instructions: |
Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).Please share your feedback with us on this Discord post. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
README.md (1)
107-109: Fix typos and naming in credits.“Asker” should be “Askar”; add article for “AYANWORKS team.”
-The CREDEBL platform is built by AYANWORKS team. -For the core SSI capabilities, it leverages the great work from multiple open-source projects such as Hyperledger Aries, Bifold, Asker, Indy, etc. +The CREDEBL platform is built by the AYANWORKS team. +For core SSI capabilities, it leverages work from multiple open-source projects such as Hyperledger Aries, Aries Bifold, Aries Askar, Hyperledger Indy, etc.
🧹 Nitpick comments (7)
README.md (7)
8-8: Replace bare URLs with Markdown links (fix MD034).Use descriptive links to satisfy markdownlint and improve readability.
-See: https://docs.docker.com/engine/install/ +See: [Docker Engine install guide](https://docs.docker.com/engine/install/) -See: https://nodejs.dev/en/learn/how-to-install-nodejs/ +See: [How to install Node.js](https://nodejs.dev/en/learn/how-to-install-nodejs/)Also applies to: 12-12
15-17: Clarify NestJS CLI usage (global vs npx).Without global install, plain
nestmay not be on PATH. Recommend either global install ornpx nest.-npm i @nestjs/cli@latest +# Option A: Global CLI +npm i -g @nestjs/cli@latest +# Option B: Use npx (no global install) +# npx nest --version
47-51: Pin NATS image version.Avoid
latestfor reproducibility.-docker pull nats:latest +docker pull nats:2
85-95: Complete the microservice list and suggest a parallel runner.Include
organizationfor consistency, and consider a single command (e.g., npm scripts/PM2) to start multiple services.nest start user [--watch] nest start ledger [--watch] nest start connection [--watch] nest start issuance [--watch] nest start verification [--watch] nest start agent-provisioning [--watch] nest start agent-service [--watch] +nest start organization [--watch]
99-103: Make the gateway URL clickable.Code fencing disables the link.
-``` -http://localhost:5000/api -``` +[http://localhost:5000/api](http://localhost:5000/api)
19-21: Consider adding a “Clone the repo” step.New contributors benefit from a first step showing clone and
cdcommands.## Setup Instructions + +### 0. Clone the repository +```bash +git clone https://github.com/credebl/platform.git +cd platform +```
70-75: Specify the API gateway project key.nest startin a monorepo defaults to the first project and may fail—use the actual project name defined innest-cli.json:-nest start [--watch] +nest start api-gateway [--watch]
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README.md(3 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
README.md
8-8: Bare URL used
(MD034, no-bare-urls)
12-12: Bare URL used
(MD034, no-bare-urls)
🔇 Additional comments (1)
README.md (1)
53-58: Use Compose v2 syntax and run detached-docker-compose up +docker compose up -dTo start only the NATS service:
docker compose up -d nats
| Version: >= 18.17.0 | ||
| See: https://nodejs.dev/en/learn/how-to-install-nodejs/ |
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Align Node.js version with repo engines/CI.
18.17+ may be outdated versus your package.json/CI. Please verify and reflect the exact supported major (LTS) here.
🏁 Script executed:
#!/bin/bash
# Extract Node "engines" and CI Node versions
fd -u package.json | xargs -I{} jq -r '.engines?.node // empty | "engines(node) in {}: \(. )"' {}
fd -u .github -t f -e yml -E '*node_modules*' | rg -nP 'setup-node|node-version|matrix:\s*node'
# Check for .nvmrc if present
fd -u .nvmrc | xargs -I{} sh -c 'printf ".nvmrc: "; cat {}'Length of output: 35
🏁 Script executed:
#!/bin/bash
# Find Node versions in GitHub Actions workflows
fd -u .github/workflows -t f -e yml --exec rg -nP 'node-version' {} -n
# Check for matrix node versions
fd -u .github/workflows -t f -e yml --exec rg -nP 'matrix:\s*node' {} -n
# Inspect .nvmrc if present
if [ -f .nvmrc ]; then
echo ".nvmrc: $(cat .nvmrc)"
else
echo ".nvmrc not found"
fiLength of output: 764
🏁 Script executed:
#!/bin/bash
# Locate all GitHub Actions workflow YAML files
find .github/workflows -type f \( -name '*.yml' -o -name '*.yaml' \) | tee /tmp/workflows.txt
# Search for Node version specifications in those workflows
xargs -a /tmp/workflows.txt -I{} rg -nP 'node-version\s*:' {}
xargs -a /tmp/workflows.txt -I{} rg -nP 'matrix:\s*node' {} Length of output: 197
Align Node.js version in README with package.json engines
In README.md (lines 11–12), replace
Version: >= 18.17.0
with
Version: >= 18
to match "engines.node": ">=18" in package.json.
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
12-12: Bare URL used
(MD034, no-bare-urls)
🤖 Prompt for AI Agents
In README.md around lines 11 to 12, the Node.js version requirement is overly
specific (">= 18.17.0") and should match package.json's "engines.node": ">=18";
update the README line to "Version: >= 18" so both files are consistent,
ensuring the README uses the same broad engine constraint as package.json.
README.md
Outdated
| ### 2. Run Prisma to Generate Database Schema | ||
|
|
||
| ```bash | ||
| cd ./libs/prisma-service/prisma | ||
| npx prisma generate | ||
| npx prisma db push | ||
| ``` |
There was a problem hiding this comment.
Order of operations will break Prisma commands.
Prisma needs dependencies installed and DATABASE_URL configured before generate/db push/seed. As written, Step 2/3 may fail.
Minimal fix: call out prerequisites inline and reference .env.
### 2. Run Prisma to Generate Database Schema
+Prerequisites: run `npm install` at repo root and create `.env` with a valid `DATABASE_URL` before executing the commands below.Also consider moving “Install Dependencies” and “Configure Environment Variables” ahead of Steps 2 and 3, or renumbering as:
- Configure Environment Variables, 2) Install Dependencies, 3) PostgreSQL, 4) Prisma generate/db push, 5) Seed.
Also applies to: 36-41, 62-69
🤖 Prompt for AI Agents
In README.md around lines 28-34 (also applicable to 36-41 and 62-69): the Prisma
commands are ordered before prerequisites and may fail because dependencies and
DATABASE_URL must be present; update the instructions to call out/configure
prerequisites inline (install project dependencies and set DATABASE_URL in .env)
before running npx prisma generate, npx prisma db push, or seeding, and either
move the "Install Dependencies" and "Configure Environment Variables" steps
ahead of the Prisma section or renumber the steps (e.g., 1 Configure Environment
Variables, 2 Install Dependencies, 3 PostgreSQL, 4 Prisma generate/db push, 5
Seed) so the README enforces the correct order.
| cd ./libs/prisma-service/prisma | ||
| npx prisma generate | ||
| npx prisma db push | ||
| ``` |
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Confirm Prisma paths and seed script exist.
Verify libs/prisma-service/prisma/schema.prisma exists and that a Prisma seed script is configured; otherwise prisma db seed will no-op or fail.
🏁 Script executed:
#!/bin/bash
fd -u 'schema.prisma' | rg -n 'libs/prisma-service/prisma/schema.prisma' || echo "schema.prisma not found at expected path"
# Check Prisma dependency and seed config
fd -u package.json | xargs -I{} jq -r 'select(.name? and (.name|test("prisma|prisma-service"))) | {file:"{}", prisma:.devDependencies?.prisma // .dependencies?.prisma, client:.dependencies?["@prisma/client"], seed:.prisma?.seed}' {}Length of output: 1404
🏁 Script executed:
#!/usr/bin/env bash
set -e
echo "Seed files under libs/prisma-service/prisma:"
fd -u 'seed.*' libs/prisma-service/prisma || echo "No seed.* files found"
if [ -f libs/prisma-service/package.json ]; then
echo "Lines containing 'prisma' in libs/prisma-service/package.json:"
grep -n '"prisma"' -n libs/prisma-service/package.json || echo "No 'prisma' config"
echo "Lines containing 'seed' in libs/prisma-service/package.json:"
grep -n '"seed"' -n libs/prisma-service/package.json || echo "No 'seed' config"
else
echo "libs/prisma-service/package.json not found"
fiLength of output: 122
Add or verify Prisma seed configuration
A seed file exists at libs/prisma-service/prisma/seed.ts, but there’s no package.json in that folder declaring a prisma.seed entry. Ensure your Prisma service’s package.json (either in libs/prisma-service/prisma or your monorepo root) includes, for example:
"prisma": {
"seed": "ts-node --transpile-only prisma/seed.ts"
}and that @prisma/client and ts-node (or equivalent) are installed, so npx prisma db seed actually runs your script.
🤖 Prompt for AI Agents
In README.md around lines 31 to 34, the docs run prisma generate/db push but do
not ensure a Prisma seed is configured; add or update a package.json either
under libs/prisma-service/prisma or at the monorepo root to include a "prisma":
{ "seed": "ts-node --transpile-only prisma/seed.ts" } entry (or an equivalent
command for your runtime), and make sure @prisma/client and ts-node (or your
chosen runner) are installed so npx prisma db seed will execute
libs/prisma-service/prisma/seed.ts.
…nts. The changes include: 1. Container name: Changed from some-postgres to credebl-postgres for better identification 2. PostgreSQL version: Specified postgres:16 instead of using the latest tag 3. Database name: Added -e POSTGRES_DB=credebl to explicitly create the database 4. Password: Changed from placeholder <secretpassword> to changeme (a proper example password) 5. Data persistence: Added volume mapping -v credebl_pgdata:/var/lib/postgresql/data to persist data 6. Multi-line format: Formatted the command with line breaks for better readability Signed-off-by: DeepDN <[email protected]>
There was a problem hiding this comment.
Actionable comments posted: 3
♻️ Duplicate comments (4)
README.md (4)
11-12: Align Node.js engines and fix markdownlint MD034.Use the same constraint as package.json and avoid a bare URL.
-### Install Node.js -Version: >= 18.17.0 -See: https://nodejs.dev/en/learn/how-to-install-nodejs/ +### Install Node.js +Version: >= 18 +See: [How to install Node.js](https://nodejs.dev/en/learn/how-to-install-nodejs/)
42-47: Ensure Prisma seed is configured and prerequisites stated.Add an explicit note so
npx prisma db seedactually runs your seed script.-### 3. Seed Initial Data +### 3. Seed Initial Data +Prerequisites: `.env` with `DATABASE_URL` and a configured Prisma seed (see `package.json` `"prisma.seed"`).Example
package.jsonsnippet (where your Prisma client lives):"prisma": { "seed": "ts-node --transpile-only prisma/seed.ts" }
73-75: Provide a minimal, copy‑pasteable .env example (align with docs.credebl.id).This reduces setup friction and matches the linked docs thread.
-### Configure Environment Variables -Configure environment variables in `.env` before you start the API Gateway. +### Configure Environment Variables +Create a `.env` before starting services, for example: + +```bash +# Database +DATABASE_URL="postgresql://credebl:changeme@localhost:5432/credebl?schema=public" +# NATS +NATS_URL="nats://localhost:4222" +# Gateway +PORT=5000 +``` + +Refer to the canonical list in the docs for additional keys.
34-40: Prisma commands require deps and DATABASE_URL first.As written, these may fail if
npm installand.envaren’t set yet.Minimal inline fix:
-### 2. Run Prisma to Generate Database Schema +### 2. Run Prisma to Generate Database Schema +Prerequisites: run `npm install` at repo root and create a `.env` with a valid `DATABASE_URL` before running the commands below.Longer-term: consider moving “Install Dependencies” and “Configure Environment Variables” before this section.
🧹 Nitpick comments (2)
README.md (2)
14-17: Make NestJS CLI optional when using npx.If you use
npx nest ...later, a global/local install is optional; clarify to avoid confusion.-### Install NestJS CLI -```bash -npm i @nestjs/cli@latest -``` +### (Optional) Install NestJS CLI +If you prefer not to use `npx`, install the CLI: +```bash +npm i -g @nestjs/cli +```
103-110: Clarify gateway URL/port source.If
PORTis configurable via.env, mention the default and reflect it: e.g., “By default http://localhost:5000/api (or http://localhost:${PORT}/api).”
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README.md(3 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
README.md
8-8: Bare URL used
(MD034, no-bare-urls)
12-12: Bare URL used
(MD034, no-bare-urls)
🔇 Additional comments (3)
README.md (3)
8-8: Avoid bare URL (MD034).Wrap the Docker link in markdown.
[raise_nitpick_refactor]-See: https://docs.docker.com/engine/install/ +See: [Docker Engine install](https://docs.docker.com/engine/install/)
25-31: PostgreSQL container command looks solid.Good: pinned major version, named container, DB/user/password, volume for persistence. Consider adding
--health-cmdlater, but not blocking.
114-114: Typo: “Askar” not “Asker.”
[raise_nitpick_refactor]-For the core SSI capabilities, it leverages the great work from multiple open-source projects such as Hyperledger Aries, Bifold, Asker, Indy, etc. +For the core SSI capabilities, it leverages the great work from multiple open-source projects such as Hyperledger Aries, Bifold, Askar, Indy, etc.
README.md
Outdated
| ### Pull NATS Docker Image | ||
|
|
||
| ``` | ||
| NATS is used for inter-service communication. The only prerequisite here is to install Docker. | ||
|
|
||
| ```bash | ||
| docker pull nats:latest | ||
| ``` |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Avoid latest; pin the NATS image.
Use a major tag for repeatable setups, or drop manual pull if Compose handles it.
-```bash
-docker pull nats:latest
-```
+```bash
+docker pull nats:2
+```🤖 Prompt for AI Agents
In README.md around lines 51 to 57, the instruction uses docker pull nats:latest
which is not repeatable; change the example to pin a major version (e.g., docker
pull nats:2) or remove the manual docker pull step entirely if docker-compose
already declares/pulls the image; update the bash block to show the chosen
approach so the README uses a stable, repeatable image reference.
README.md
Outdated
| ### Run NATS using Docker Compose | ||
| The `docker-compose.yml` file is available in the root folder. | ||
|
|
||
| ``` | ||
| ```bash | ||
| docker-compose up | ||
| ``` |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Prefer modern Compose syntax and run detached.
Use docker compose and add -d.
-```bash
-docker-compose up
-```
+```bash
+docker compose up -d
+```🤖 Prompt for AI Agents
In README.md around lines 59 to 64, the instruction uses legacy docker-compose
and runs in foreground; update the example to use the modern Docker Compose CLI
and run detached by replacing "docker-compose up" with "docker compose up -d"
and ensure the fenced code block language remains "bash" and contains only the
new command.
| ```bash | ||
| nest start [--watch] | ||
| ``` |
There was a problem hiding this comment.
Use npx for Nest commands to avoid PATH issues.
Running nest directly may fail without a global install; npx works out‑of‑the‑box.
-```bash
-nest start [--watch]
-```
+```bash
+npx nest start [--watch]
+```
-```bash
-nest start organization [--watch]
-```
+```bash
+npx nest start organization [--watch]
+```
-```bash
-nest start user [--watch]
-nest start ledger [--watch]
-nest start connection [--watch]
-nest start issuance [--watch]
-nest start verification [--watch]
-nest start agent-provisioning [--watch]
-nest start agent-service [--watch]
-```
+```bash
+npx nest start user [--watch]
+npx nest start ledger [--watch]
+npx nest start connection [--watch]
+npx nest start issuance [--watch]
+npx nest start verification [--watch]
+npx nest start agent-provisioning [--watch]
+npx nest start agent-service [--watch]
+```Also applies to: 88-89, 94-101
🤖 Prompt for AI Agents
In README.md around lines 79-81 (and also apply same change to lines 88-89 and
94-101), the examples call the global "nest" binary which can fail if not
installed; update each code block to prefix commands with "npx " (e.g., replace
"nest start ..." with "npx nest start ...") so the commands work without a
global install and ensure all listed service start commands are similarly
updated.
README.md
Outdated
| ``` | ||
|
|
||
| **Run prisma to generate db schema** | ||
| ### 2. Run Prisma to Generate Database Schema |
There was a problem hiding this comment.
Hi @DeepakNemad you can update to maintain consistency of bullet and numbering as well in the document.
For example, Setup Instructions have numbering but other headings doesn't (Install NATS Message Broker etc)
There was a problem hiding this comment.
Hello @ankita-p17
- Thanks for the suggestions, As per the suggestion I have made a changes and pushed the updated changes to same branch I request you to please review it once.
…tanding in README.md Signed-off-by: DeepDN <[email protected]>
|
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (7)
README.md (7)
11-12: Align Node.js version with package.json enginesUse a broad major to match
"engines.node": ">=18".-Version: >= 18.17.0 +Version: >= 18
73-75: Provide a minimal .env example (copy‑pasteable)Reduces setup friction and aligns with docs.credebl.id.
-### 4.2. Configure Environment Variables -Configure environment variables in `.env` before you start the API Gateway. +### 4.2. Configure Environment Variables +Create a `.env` file before starting services, for example: + +```bash +# Database +DATABASE_URL="postgresql://credebl:changeme@localhost:5432/credebl?schema=public" +# NATS +NATS_URL="nats://localhost:4222" +# Gateway +PORT=5000 +``` +Note: Use strong, non‑default credentials outside local development.
55-57: Avoidlatest; pin NATS imageUse a stable tag or rely on Compose to pull.
-```bash -docker pull nats:latest -``` +```bash +docker pull nats:2 +```
62-64: Use modern Compose syntax and run detachedSwitch to
docker composeand add-d.-```bash -docker-compose up -``` +```bash +docker compose up -d +```
79-101: Prefernpx nestto avoid global CLI assumptionsWorks without a global install; also keep Step 1.3 optional or remove.
-```bash -nest start [--watch] -``` +```bash +npx nest start [--watch] +``` -```bash -nest start organization [--watch] -``` +```bash +npx nest start organization [--watch] +``` -```bash -nest start user [--watch] -nest start ledger [--watch] -nest start connection [--watch] -nest start issuance [--watch] -nest start verification [--watch] -nest start agent-provisioning [--watch] -nest start agent-service [--watch] -``` +```bash +npx nest start user [--watch] +npx nest start ledger [--watch] +npx nest start connection [--watch] +npx nest start issuance [--watch] +npx nest start verification [--watch] +npx nest start agent-provisioning [--watch] +npx nest start agent-service [--watch] +```
34-47: Ensure Prisma seed is configured to actually runAdd a note that
package.jsonmust define a Prisma seed script (e.g.,ts-node prisma/seed.ts) sonpx prisma db seedexecutes.
34-41: Prisma steps require deps and DATABASE_URL firstAs written,
npx prisma generate/db pushmay fail withoutnpm installand a valid.env.-### 2.2. Run Prisma to Generate Database Schema +### 2.2. Run Prisma to Generate Database Schema +Prerequisites: run `npm install` at the repo root and create a `.env` with a valid `DATABASE_URL` before running the commands below.
🧹 Nitpick comments (6)
README.md (6)
8-8: Fix markdownlint MD034 (bare URL)Use a proper Markdown link.
-See: https://docs.docker.com/engine/install/ +See: [Docker Engine installation](https://docs.docker.com/engine/install/)
12-12: Fix markdownlint MD034 (bare URL)Use a proper Markdown link.
-See: https://nodejs.dev/en/learn/how-to-install-nodejs/ +See: [How to install Node.js](https://nodejs.dev/en/learn/how-to-install-nodejs/)
14-17: Make NestJS CLI install optional or globalIf keeping this step, install globally; otherwise remove in favor of
npx.[suggest_minor_issue]
-### 1.3. Install NestJS CLI +### 1.3. (Optional) Install NestJS CLI globally ```bash -npm i @nestjs/cli@latest +npm i -g @nestjs/cli@latest--- `105-109`: **Prefer a clickable inline link over a code block** Minor readability improvement. ```diff -``` -http://localhost:5000/api -``` +Access via: http://localhost:5000/api
113-115: Fix typo: “Asker” → “Askar”Refers to Hyperledger Aries Askar.
-For the core SSI capabilities, it leverages the great work from multiple open-source projects such as Hyperledger Aries, Bifold, Asker, Indy, etc. +For the core SSI capabilities, it leverages the great work from multiple open-source projects such as Hyperledger Aries, Bifold, Askar, Indy, etc.
7-8: Clarify Compose v2 availabilityCompose v2 ships with Docker; adjust wording.
-### 1.1. Install Docker and Docker Compose +### 1.1. Install Docker (includes Docker Compose v2)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README.md(3 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
README.md
8-8: Bare URL used
(MD034, no-bare-urls)
12-12: Bare URL used
(MD034, no-bare-urls)
🔇 Additional comments (1)
README.md (1)
25-31: Postgres command improvements look goodPinned image, named volume, explicit DB/user creds — all solid for local dev. Consider adding a one‑liner warning not to use
changemein prod.
Fixes #1275
Summary by CodeRabbit