From 0fdb346fa2bced385f4df75eb6593594442a6500 Mon Sep 17 00:00:00 2001 From: SpandanaKona <2400032836@kluniversity.in> Date: Mon, 24 Nov 2025 13:08:31 +0530 Subject: [PATCH 1/2] Add CREDEBL UI User Guide documentation Added a comprehensive user guide covering the CREDEBL UI modules including Users, Ledger, Organizations, Connections, Issuance, and Verification. Includes navigation steps, best practices, troubleshooting tips, and relevant resource links. Signed-off-by: SpandanaKona <2400032836@kluniversity.in> --- CREDEBL-UI-User-Guide.md | 74 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 CREDEBL-UI-User-Guide.md diff --git a/CREDEBL-UI-User-Guide.md b/CREDEBL-UI-User-Guide.md new file mode 100644 index 0000000..e290b24 --- /dev/null +++ b/CREDEBL-UI-User-Guide.md @@ -0,0 +1,74 @@ +# CREDEBL UI User Guide + +## Introduction +CREDEBL is an open-source Self-Sovereign Identity (SSI) and Verifiable Credentials platform. +This guide helps users navigate the CREDEBL User Interface (UI) efficiently. + +## Accessing the Platform +1. Open your browser. +2. Navigate to your environment: + - Local development: http://localhost:5000 + - Hosted environment: as provided by your administrator +3. Log in using your credentials or developer account for local setups. + +## Dashboard Overview +- **Users**: Manage users and their credentials. +- **Ledger**: View issued credentials and verification history. +- **Organizations**: Manage organizational accounts and credentials. +- **Connections**: Track SSI connections and their status. +- **Issuance & Verification**: Issue credentials or verify existing ones. + +## Navigation +- Use the **sidebar menu** to switch between modules. +- Hover over icons to see tooltips explaining their functions. +- Use search bars and filters to quickly locate records. + +## Modules + +### Users +- **Add User**: Fill required fields and click Create. +- **Search Users**: Filter by ID, name, or email. +- **View Details**: Click on a user to view full credentials and history. + +### Ledger +- Lists all issued credentials with columns like credential ID, type, issuer, and status. +- Filter results by type, status, or date range. + +### Organizations +- **Add Organization**: Provide name, type, and assign credentials. +- **Manage Credentials**: Assign, revoke, or view credentials for organizations. + +### Connections +- Shows active SSI connections including status, last activity, and associated users. +- Use filters to locate specific connections. + +### Issuance & Verification +- **Issue Credential**: + 1. Select credential type. + 2. Choose recipient (user or organization). + 3. Fill required fields. + 4. Click Issue Credential. +- **Verify Credential**: + 1. Enter credential ID. + 2. System checks ledger. + 3. Displays verification result. + +## Best Practices +- Verify credentials before issuing. +- Ensure all environment variables are correctly configured. +- Restart services if UI is not reflecting updates. + +## Troubleshooting +- **UI not accessible**: Confirm API Gateway and microservices are running. +- **Credential issuance errors**: Check Prisma database schema and restart services. +- **UI outdated**: Clear browser cache or restart frontend. + +## Additional Resources +- CREDEBL GitHub Repository: https://github.com/credebl/platform +- Backend Setup & Environment Guide: README.md +- Docker Documentation: https://docs.docker.com/ +- NATS Documentation: https://docs.nats.io/ + +--- + +*This guide is maintained by contributors and will be updated as CREDEBL evolves.* From 2828d37c43670412140e7291b41c2421e9e2743a Mon Sep 17 00:00:00 2001 From: SpandanaKona <2400032836@kluniversity.in> Date: Wed, 26 Nov 2025 16:28:35 +0530 Subject: [PATCH 2/2] Revise CREDEBL UI User Guide for clarity and updates Updated the CREDEBL UI User Guide to include versioning, improved instructions, and additional details for various sections. Signed-off-by: SpandanaKona <2400032836@kluniversity.in> --- CREDEBL-UI-User-Guide.md | 152 ++++++++++++++++++++++++++++----------- 1 file changed, 110 insertions(+), 42 deletions(-) diff --git a/CREDEBL-UI-User-Guide.md b/CREDEBL-UI-User-Guide.md index e290b24..1f732b3 100644 --- a/CREDEBL-UI-User-Guide.md +++ b/CREDEBL-UI-User-Guide.md @@ -1,74 +1,142 @@ # CREDEBL UI User Guide +**Version:** v0.1 — 2025-11-26 + ## Introduction -CREDEBL is an open-source Self-Sovereign Identity (SSI) and Verifiable Credentials platform. -This guide helps users navigate the CREDEBL User Interface (UI) efficiently. + +CREDEBL is an open-source Self‑Sovereign Identity (SSI) and Verifiable Credentials platform. +See the code repository: [CREDEBL Platform](https://github.com/credebl/platform) + +This guide helps users navigate the CREDEBL User Interface (UI), perform common tasks, and troubleshoot issues. ## Accessing the Platform + 1. Open your browser. 2. Navigate to your environment: - - Local development: http://localhost:5000 - - Hosted environment: as provided by your administrator -3. Log in using your credentials or developer account for local setups. + - Local development: `http://localhost:5000` (default; verify `FRONTEND_PORT` or `FRONTEND_URL` in your README or `.env`) + - Hosted environment: `https://` — provided by your administrator +3. Log in using your assigned account: + - Local dev: document default test credentials and roles in the README (example roles: Administrator, Issuer, Verifier) + - If no defaults exist, document where to obtain or create seed users (backend README or setup scripts) ## Dashboard Overview -- **Users**: Manage users and their credentials. -- **Ledger**: View issued credentials and verification history. -- **Organizations**: Manage organizational accounts and credentials. -- **Connections**: Track SSI connections and their status. -- **Issuance & Verification**: Issue credentials or verify existing ones. + +- **Users** — manage users, view credentials, and inspect activity logs (create/edit/delete, assign credentials) +- **Ledger** — view issued credentials, verification history, search by credential ID or DID +- **Organizations** — create/manage organizations, assign roles and credentials +- **Connections** — inspect SSI connections, invitation status, and last activity +- **Issuance & Verification** — issue credentials from templates and verify with detailed results (signature, revocation, schema checks) ## Navigation -- Use the **sidebar menu** to switch between modules. -- Hover over icons to see tooltips explaining their functions. -- Use search bars and filters to quickly locate records. + +- Use the sidebar menu to switch between modules +- Hover over icons to see tooltips explaining their functions +- Tip: Use the global search (top bar) to look up credential IDs and DIDs quickly. Filters accept exact IDs and date ranges +- Use search bars and filters to quickly locate records ## Modules ### Users -- **Add User**: Fill required fields and click Create. -- **Search Users**: Filter by ID, name, or email. -- **View Details**: Click on a user to view full credentials and history. + +- **Add User** — fill required fields (display name, email, unique ID or DID, role) and click Create. Required: name, email, role. Optional: metadata and initial credentials +- **Search Users** — filter by ID, name, email, or DID +- **View Details** — click a user to view credentials, connections, and event history +- **Permission note** — only Administrator or Issuer roles can issue credentials. Document role capabilities in the backend README ### Ledger -- Lists all issued credentials with columns like credential ID, type, issuer, and status. -- Filter results by type, status, or date range. + +- Lists all issued credentials with columns: credential ID, type, issuer, issuance date, and status +- Status values: active, revoked, pending, expired +- Filter and sort by type, status, date range, or issuer ### Organizations -- **Add Organization**: Provide name, type, and assign credentials. -- **Manage Credentials**: Assign, revoke, or view credentials for organizations. + +- **Add Organization** — provide name, organization type (issuer, verifier, partner), and assign org admins +- **Manage Credentials** — attach credential templates, assign or revoke credentials for organization members ### Connections -- Shows active SSI connections including status, last activity, and associated users. -- Use filters to locate specific connections. + +- Shows active SSI connections including status, last activity, and associated users +- To establish a connection, the recipient must accept an invitation (DID exchange). See backend connection API in the repo README +- Use filters to locate connections by connection ID, user, or DID ### Issuance & Verification -- **Issue Credential**: - 1. Select credential type. - 2. Choose recipient (user or organization). - 3. Fill required fields. - 4. Click Issue Credential. -- **Verify Credential**: - 1. Enter credential ID. - 2. System checks ledger. - 3. Displays verification result. + +**Issue Credential:** + +1. Select a credential template +2. Choose recipient (user DID or organization DID) +3. Fill required fields — fields are marked on the form + Example payload: `{ "name": "Jane Doe", "email": "jane@example.com", "id": "did:key:z6M..." }` +4. Click Issue Credential — UI shows issuance progress and returns a credential ID. Save the credential ID + +If issuance fails, check issuer service logs and database connectivity + +**Verify Credential:** + +1. Enter credential ID or upload credential JSON +2. The system validates cryptographic proofs against the ledger/trust anchors +3. The UI displays VALID / INVALID and details of any failing checks (signature, revocation, schema) ## Best Practices -- Verify credentials before issuing. -- Ensure all environment variables are correctly configured. -- Restart services if UI is not reflecting updates. + +- Verify credential data before issuing to avoid invalid ledger entries +- Required environment variables (document exact names and values in deployment docs): + - `DATABASE_URL` + - `LEDGER_URL` + - `NATS_URL` (or other message broker) + - `API_GATEWAY_URL` + - `JWT_SIGNING_KEY` (or OIDC configuration) +- Use HTTPS/TLS and proper authentication in production. Never commit secrets to the repository +- Use test networks and test DIDs for development +- Log and monitor issuer, verifier, ledger, and messaging services for observability +- Restart services if the UI is not reflecting updates (see Troubleshooting) ## Troubleshooting -- **UI not accessible**: Confirm API Gateway and microservices are running. -- **Credential issuance errors**: Check Prisma database schema and restart services. -- **UI outdated**: Clear browser cache or restart frontend. + +- **UI not accessible:** + - Confirm frontend container/process is running (`docker-compose ps | grep frontend`) + - Check logs: `docker-compose logs -f frontend` + - Confirm API gateway and microservices are running: `docker-compose logs -f api-gateway` + - Check browser console for CORS/network errors +- **Credential issuance errors:** + - Check issuer service logs: `docker-compose logs -f issuer` + - Look for Prisma/DB errors; confirm `DATABASE_URL` and DB connectivity + - If schema changed: run migrations (`npx prisma migrate deploy` or `prisma migrate dev`) +- **Verification failures:** + - Confirm verifier can reach the ledger and has correct trust anchors/public keys + - Inspect verifier logs for signature or revocation check errors +- **UI shows stale data:** Hard refresh browser (Ctrl+F5), clear cache, or restart frontend container: `docker-compose restart frontend` +- **Message/event-driven issues:** verify NATS or the configured message broker is running and `NATS_URL` is correct + +## Known issues & workarounds + +- **Credential issuance fails with "database error"** + Cause: missing Prisma migrations or wrong `DATABASE_URL` + Workaround: run migrations, confirm `DATABASE_URL`, restart services, check issuer logs +- **Connection remains "Pending"** + Cause: messaging broker (NATS) down or network misconfiguration + Workaround: ensure NATS is running, verify `NATS_URL`, check logs +- **Revocation not reflected in verification** + Cause: verifier cache or delayed propagation of revocation events + Workaround: restart verifier and confirm revocation events are published and consumed + +## Environment & Setup Notes + +- **Local dev tips:** + - Bring up services: `docker-compose up --build` + - Check running services: `docker-compose ps` + - Tail logs: `docker-compose logs -f ` + - If backend schema changes, run migrations and restart dependent services +- Document any additional env vars or secrets required in the repository README ## Additional Resources -- CREDEBL GitHub Repository: https://github.com/credebl/platform -- Backend Setup & Environment Guide: README.md -- Docker Documentation: https://docs.docker.com/ -- NATS Documentation: https://docs.nats.io/ + +- CREDEBL GitHub Repository: [https://github.com/credebl/platform](https://github.com/credebl/platform) +- Backend Setup & Environment Guide: [README.md](https://github.com/credebl/platform/blob/main/backend/README.md) +- Docker Documentation: [https://docs.docker.com/](https://docs.docker.com/) +- NATS Documentation: [https://docs.nats.io/](https://docs.nats.io/) --- -*This guide is maintained by contributors and will be updated as CREDEBL evolves.* +*This guide is maintained by contributors. To propose changes, open a PR in the credebl/docs repository.*