impierce · Copilot · Oct 1, 2025 · Oct 1, 2025 · Oct 1, 2025 · Oct 1, 2025
@@ -1,4 +1,4 @@
-# SSI Agent
+# UniCore
 
 [![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)
 [![GitHub License](https://img.shields.io/github/license/impierce/ssi-agent)](https://github.com/impierce/ssi-agent/blob/HEAD/LICENSE)
@@ -8,19 +8,28 @@
 
 [![twelve-factor-app](https://img.shields.io/badge/factors-twelve-blue)](https://12factor.net)
 
+**UniCore** is an eIDAS 2.0-compliant Self-Sovereign Identity (SSI) agent that enables organizations to issue, verify, and manage verifiable credentials. It connects European Identity Wallets to your IT systems using open standards like OpenID4VCI, OpenID4VP, and W3C Verifiable Credentials.
+
 ---
 
+## Getting Started
+
+1. **Quick Start**: Follow the [quick start guide](./docs/introduction/quick-start.md) to deploy UniCore locally and issue your first credential
+2. **API Specification**: [Explore the REST API](./agent_api_rest/README.md) to understand available endpoints
+3. **Configuration**: Review [configuration options](./docs/configuration/CONFIGURATION.md) for customizing your deployment
+4. **Build & Run**: [Deploy with Docker](./agent_application/docker/README.md) for local development
+
 ## API specification
 
 [Follow these instructions](./agent_api_rest/README.md) to inspect the REST API.
 
 ## Build & Run
 
-Build and run the **SSI Agent** in a local Docker environment following [these steps](./agent_application/docker/README.md).
+Build and run **UniCore** in a local Docker environment following [these steps](./agent_application/docker/README.md).
 
 ## Configuration
 
-All configuration options are documented [here](./agent_application/CONFIGURATION.md).
+All configuration options are documented [here](./docs/configuration/CONFIGURATION.md).
 
 ## Breaking changes
 

@@ -1,6 +1,6 @@
-# agent_api_rest
+# UniCore REST API
 
-A lightweight REST API for the SSI Agent.
+A lightweight REST API for UniCore.
 
 UniCore's REST API is currently still in the pre-release stage meaning that the API is still under active development.
 Breaking changes may occur before the API reaches a stable version.

@@ -5,7 +5,7 @@
 In case you want to build the image in isolation, you can run the following command from within the directory `/agent_application`:
 
 ```bash
-docker build -f docker/Dockerfile -t ssi-agent ..
+docker build -f docker/Dockerfile -t unicore ..
 ```
 
 ## Local development
@@ -28,7 +28,7 @@ volumes:
 3. _(optional)_ In case you are interested in the events that UniCore produces, you can configure a HTTP Event Publisher that sends
    certain events to a URL of your choice. More information about the HTTP Event Publisher [can be found here](../../agent_event_publisher_http/README.md).
 
-4. To start the **SSI Agent**, a **Postgres** database along with **pgadmin** (Postgres Admin Interface) simply run:
+4. To start **UniCore**, a **Postgres** database along with **pgadmin** (Postgres Admin Interface) simply run:
 
 ```bash
 docker compose up
@@ -64,4 +64,4 @@ To integrate just-in-time data request events into your workflow, adhere to the
 3. The HTTP Event Publisher dispatches the event to the external system. Leveraging the provided identifiers, the external system generates and signs the credential, then submits it to UniCore's `/v0/credentials` endpoint. Refer to the [API specification](../../agent_api_rest/README.md)) for additional details on endpoint usage.
 
 By default, UniCore will wait up to 1000 ms for the signed credential to arrive. This parameter can be changed by
-setting the `AGENT_API_REST_EXTERNAL_SERVER_RESPONSE_TIMEOUT_MS` environment variable.
+setting the `UNICORE__EXTERNAL_SERVER_RESPONSE_TIMEOUT_MS` environment variable.
@@ -1,6 +1,6 @@
-# agent_event_publisher_http
+# UniCore HTTP Event Publisher
 
-A simple HTTP event publisher for the SSI Agent.
+A simple HTTP event publisher for UniCore.
 
 To make use of this publisher you need to configure it by adding the `http` object to your configuration file.
 

@@ -0,0 +1,18 @@
+# UniCore Holder Agent
+
+This module implements credential holding functionality for UniCore, allowing the management of verifiable credentials from a holder's perspective.
+
+## Components
+
+- **Credential**: Managing held credentials and their associated data
+- **Offer**: Processing credential offers received from issuers
+- **Presentation**: Creating and managing verifiable presentations of held credentials
+
+## Features
+
+- Credential storage and management
+- Credential offer processing
+- Verifiable presentation creation
+- Integration with UniCore's CQRS event-sourcing architecture
+
+This module is part of UniCore's hexagonal architecture, implementing core business logic for credential holding operations.
@@ -0,0 +1,27 @@
+# UniCore Identity Agent
+
+This module manages decentralized identity (DID) documents and related identity components for UniCore.
+
+## Components
+
+- **Document**: DID document creation, management, and hosting
+- **Service**: DID document service endpoints management
+- **Connection**: Managing connections to external identity services
+- **Profile**: Managing identity profile information and display data
+
+## Features
+
+- DID document creation and management
+- Multiple DID method support (did:web, did:iota, etc.)
+- Service endpoint configuration
+- Domain linkage support
+- Profile and display information management
+- Integration with UniCore's CQRS event-sourcing architecture
+
+## Supported DID Methods
+
+- `did:web` - Web-based DIDs hosted via HTTPS
+- `did:iota` - IOTA-based decentralized identifiers
+- Additional methods may be supported based on configuration
+
+This module enables UniCore to manage its decentralized identity, publish DID documents, and interact with other entities in the SSI ecosystem.
@@ -0,0 +1,36 @@
+# UniCore Procedural Macros
+
+This module provides procedural macros used throughout the UniCore codebase to reduce boilerplate and ensure consistency.
+
+## Macros
+
+### `#[derive(Config)]`
+
+A procedural macro that automatically generates configuration loading code for structs. This macro enables:
+
+- Loading configuration values from provisioned sources
+- Applying environment-specific defaults (development, production)
+- Struct validation
+- Support for custom transformation functions
+
+#### Usage
+
+```rust
+#[derive(Config)]
+struct MyConfig {
+    #[config(default = "42", development_default = "100")]
+    value: u32,
+
+    #[config(production_default = "https://prod.example.com")]
+    url: String,
+}
+```
+
+#### Attributes
+
+- `default = "value"`: Default value for all environments
+- `development_default = "value"`: Default value for development environment
+- `production_default = "value"`: Default value for production environment
+- `transform_with = "function"`: Custom transformation function to apply
+
+This macro is essential for UniCore's configuration system, providing a declarative way to define environment-specific configuration with sensible defaults.
@@ -0,0 +1,23 @@
+# UniCore Shared Components
+
+This module contains shared utilities, configurations, and common functionality used across all UniCore agent modules.
+
+## Components
+
+- **Config**: Configuration management and validation
+- **Application State**: Shared application state management
+- **Custom Queries**: Common query implementations for CQRS
+- **Error Handling**: Standardized error types and handling
+- **Handlers**: Shared command and query handlers
+- **Profile**: Common profile-related utilities
+- **URL Utils**: URL manipulation and validation utilities
+
+## Features
+
+- Centralized configuration management
+- Common error types and handling patterns
+- Shared CQRS query and command patterns
+- Utility functions for URL handling and validation
+- Profile and display data structures
+
+This module ensures consistency across all UniCore components and provides a foundation for the hexagonal architecture implementation.
@@ -0,0 +1,24 @@
+# UniCore Verification Agent
+
+This module implements credential verification functionality for UniCore, handling the verification of verifiable credentials and presentations.
+
+## Components
+
+- **Authorization Request**: Managing authorization requests for credential verification
+- **Generic OID4VC**: Generic OpenID for Verifiable Credentials functionality
+
+## Features
+
+- Verifiable credential verification
+- Verifiable presentation verification
+- Authorization request processing
+- OpenID4VP (OpenID for Verifiable Presentations) support
+- Integration with UniCore's CQRS event-sourcing architecture
+
+This module enables UniCore to act as a verifier in SSI ecosystems, validating credentials and presentations according to established standards.
+
+## Standards Supported
+
+- OpenID for Verifiable Presentations (OpenID4VP)
+- W3C Verifiable Credentials Data Model
+- DID (Decentralized Identifiers) resolution
@@ -47,8 +47,17 @@ This overview is still a work in progress. You can refer to the [example.config.
 
 ### Application URL
 
-UniCore's application URL. This value represents the self-aware URL of the application. It is used for internal
-communication and should not be exposed to clients or identity wallets.
+UniCore's application URL. This value represents the internal URL where the application listens for requests. It is used for:
+- Internal service communication
+- Health checks and monitoring
+- Administrative endpoints
+- Container-to-container communication in Docker environments
+
+:::warning
+
+The `APPLICATION_URL` should **not** be directly exposed to external clients or identity wallets for security reasons.
+
+:::
 
 :::note
 
@@ -63,15 +72,26 @@ The `UNICORE__APPLICATION_URL` may include a path segment, which will be treated
 #### Example
 
 ```yaml
-application_url: http://localhost:3033/my/base/path
+application_url: http://localhost:3033
 ```
 
 ### Public URL
 
-UniCore's public URL. This value is communicated to clients and identity wallets and should be publicly accessible. When
-not set, it defaults to the value of `UNICORE__APPLICATION_URL`.
+UniCore's public URL. This value is communicated to external clients and identity wallets and must be publicly accessible. It is used for:
+- Credential offers shared with wallets
+- Authorization endpoints accessed by external clients
+- DID document hosting (for did:web)
+- Public API endpoints
 
-<!-- TODO: In production, should we require that `UNICORE__PUBLIC_URL` is always explicitly set, rather than defaulting to the value of `UNICORE__APPLICATION_URL`? This would help prevent accidental exposure of internal URLs to clients. -->
+When not set, it defaults to the value of `UNICORE__APPLICATION_URL`.
+
+:::note
+
+In production deployments, the `PUBLIC_URL` typically differs from `APPLICATION_URL`. For example:
+- `APPLICATION_URL`: `http://unicore:3033` (internal container URL)
+- `PUBLIC_URL`: `https://issuer.example.com` (external domain with TLS)
+
+:::
 
 :::note
 
@@ -265,33 +285,32 @@ event_store:
   connection_string: postgresql://user:password@database:5432/demo
 ```
 
-<!--
-## More configuration options
-
-| Name                                                    | Description                                                       | Default value | Accepted values |
-| ------------------------------------------------------- | ----------------------------------------------------------------- | ------------- | --------------- |
-| `UNICORE__BASE_PATH`                                    | A base path can be set if needed.                                 | -             | string          |
-| `UNICORE__CORS_ENABLED`                                 | Enable CORS (permissive). Only required for browser-based access. | `false`       | boolean         |
-| `UNICORE__DID_METHODS__DID_WEB__ENABLED`                | Create and host a `did:web` DID document.                         | `false`       | boolean         |
-| `UNICORE__SIGNING_ALGORITHMS_SUPPORTED__EDDSA__ENABLED` | Toggles the algorithm allowed for cryptographic operations.       | `true`        | boolean         |
-| `UNICORE__DOMAIN_LINKAGE_ENABLED`                       | Enable domain linkage (only works with `did:web`).                | -             | boolean         |
-| `UNICORE__EXTERNAL_SERVER_RESPONSE_TIMEOUT_MS`          | The timeout for external server responses (in milliseconds).      | `1000`        | integer         |
--->
-
-<!-- TODO: How to document all other DID methods? -->
-<!-- TODO: VP_FORMATS -->
-<!-- TODO: EVENT_PUBLISHERS: even configured through env vars? -->
-
-<!--
-## Secret Management
-
-| Name                                           | Description                                       | Default value | Accepted values               |
-| ---------------------------------------------- | ------------------------------------------------- | ------------- | ----------------------------- |
-| `UNICORE__SECRET_MANAGER__STRONGHOLD_PATH`     | The path to the stronghold file.                  | -             | `/var/lib/unicore/stronghold` |
-| `UNICORE__SECRET_MANAGER__STRONGHOLD_PASSWORD` | The password to unlock the stronghold.            | -             | -                             |
-| `UNICORE__SECRET_MANAGER__ISSUER_EDDSA_KEY_ID` | The key ID of the EDDSA (Ed25519) key to be used. | -             | -                             |
-| `UNICORE__SECRET_MANAGER__ISSUER_ES256_KEY_ID` | The key ID of the ES256 key to be used.           | -             | -                             |
--->
+## Additional Configuration Options
+
+### CORS
+Enable CORS (permissive) for browser-based access.
+
+| Environment variable  | `config.yaml` |
+| --------------------- | ------------- |
+| `UNICORE__CORS_ENABLED` | `cors_enabled` |
+
+Default: `false`
+
+### Domain Linkage
+Enable domain linkage (only works with `did:web`).
+
+| Environment variable              | `config.yaml`         |
+| --------------------------------- | --------------------- |
+| `UNICORE__DOMAIN_LINKAGE_ENABLED` | `domain_linkage_enabled` |
+
+### External Server Response Timeout
+The timeout for external server responses (in milliseconds).
+
+| Environment variable                         | `config.yaml`                        |
+| -------------------------------------------- | ------------------------------------ |
+| `UNICORE__EXTERNAL_SERVER_RESPONSE_TIMEOUT_MS` | `external_server_response_timeout_ms` |
+
+Default: `1000`
 
 ## Look and Feel
 
@@ -300,5 +319,3 @@ event_store:
 Setting display values is currently not supported through environment variables. Please refer to `config.yaml`.
 
 :::
-
-<!-- TODO: DISPLAY_0_NAME: even configured through env vars? -->
@@ -95,10 +95,10 @@ up`, or ensure that the variable is available in your environment.
 
 ### 5. Update the Docker Compose file
 
-Open the `compose.yaml` file in a text editor and update the `image` value for the `ssi-agent` service to `impiercetechnologies/ssi-agent:1.0.0-beta.8` [(or a newer version)](https://github.com/impierce/ssi-agent/releases).
+Open the `compose.yaml` file in a text editor and update the `image` value for the `ssi-agent` service to `impiercetechnologies/ssi-agent:1.0.0-beta.12` [(or a newer version)](https://github.com/impierce/ssi-agent/releases).
 
 ```yaml
-ssi-agent: impiercetechnologies/ssi-agent:1.0.0-beta.8
+ssi-agent: impiercetechnologies/ssi-agent:1.0.0-beta.12
 ```
 
 ---