TBD54566975 · decentralgabe · Jul 28, 2023 · Jul 28, 2023 · Jul 28, 2023 · Jul 28, 2023
diff --git a/README.md b/README.md
@@ -6,85 +6,56 @@
 
 # ssi-service
 
-A web service that exposes the ssi-sdk as an HTTP API. Support operations for Verifiable Credentials, Decentralized Identifiers and things Self Sovereign Identity!
-
-## Introduction
-The Self Sovereign Identity Service (SSIS) facilitates all things relating to [DIDs](https://www.w3.org/TR/did-core/)
-and [Verifiable Credentials](https://www.w3.org/TR/vc-data-model) - in a box! The service is a part of a larger
-Decentralized Web Platform architecture which you can learn more about in our
-[collaboration repo](https://github.com/TBD54566975/collaboration).
+The Self Sovereign Identity Service (SSIS) is a RESTful web service that facilitates all things relating
+to [DIDs](https://www.w3.org/TR/did-core/),
+[Verifiable Credentials](https://www.w3.org/TR/vc-data-model) and their related standards-based interactions. Most of
+the functionality in this service
+relies upon the SSI primitives exposed in the [SSI-SDK](https://github.com/TBD54566975/ssi-sdk) project.
 
 ## Core Functionality
-- Create and manage Decentralized Identifiers
-- Create and manage Verifiable Credentials
-- Credential Suspension
-- Interacting with the standards around Verifiable Credentials such as
-  - Credential Revocations
-  - Applying for Credentials
-  - Exchanging Credentials
-  - Data Schemas (for credentials and other verifiable data)
-
-## Use Cases (more to come!)
-### Business: Issuing Verifiable Credentials <br />
-[Follow Tutorial](https://developer.tbd.website/blog/issue-verifiable-credential-manually)
-
-Steps to issue an Employment Status Credential:
-1. Spin up and host the SSI-Service
-2. Add the ability for your employees to click 'apply for a credential' on your internal EMS (should we show a front end button code example)
-3. [Create an Issuer DID](https://github.com/TBD54566975/ssi-service/blob/eabbb2a58eec06ce3998d088811c4afc53026afd/integration/common.go#L38) for your business
-4. [Create a Schema](https://github.com/TBD54566975/ssi-service/blob/eabbb2a58eec06ce3998d088811c4afc53026afd/integration/common.go#L90)
-5. [Create a Credential Manifest](https://github.com/TBD54566975/ssi-service/blob/main/integration/common.go#L180)
-6. [Submit a Credential Application](https://github.com/TBD54566975/ssi-service/blob/eabbb2a58eec06ce3998d088811c4afc53026afd/integration/common.go#L199)
-
-## Configuration
 
-Managed via:
-[TOML](https://toml.io/en/) [file](config/dev.toml)
-
-There are sets of configuration values for the server (e.g. which port to listen on), the services (e.g. which database to use),
-and each service. Each service may define specific configuration, such as which DID methods are enabled for the DID
-service.
-
-### Key Management
+- Lifecycle management for Decentralized Identifiers
+    - Multiple local, web, and blockchain methods supported
+- Create and manage Verifiable Credentials
+    - Multiple securing mechanisms
+    - Data schemas using JSON Schema
+    - Lifecycle management with credential status (revocation, suspension, etc.)
+- More robust DID and Verifiable Credential interactions such as...
+    - Enabling the application of credentials
+    - Verifying sets of credentials with custom logic
+    - Linking a DID to a web domain
+    - Integration into your existing systems with webhooks
+    - Trust management
+- And much more!
 
-SSI-service can store keys that are used to digitally sign credentials (and other data). All such keys are encrypted at
-the application before being stored using a MasterKey (a.k.a. a Key Encryption Key or KEK). The MasterKey can be
-generated automatically during boot time, or we can use the MasterKey housed in an external Key 
-Management System (KMS) like GCP KMS or AWS KMS.
+## Documentation
 
-For production deployments, using external KMS is strongly recommended.
+### Vision, Features, and Development
 
-To use an external KMS: 
-1. Create a symmetric encryption key in your KMS. You MUST select the algorithm that uses AES-256 block cipher in Galois/Counter Mode (GCM). At the time of writing, this is the only algorithm supported by AWS and GCP.
-2. Set the `master_key_uri` field of the `[services.keystore]` section using the format described in [tink](https://github.com/google/tink/blob/9bc2667963e20eb42611b7581e570f0dddf65a2b/docs/KEY-MANAGEMENT.md#key-management-systems)
-(we use the tink library under the hood).
-3. Set the `kms_credentials_path` field of the `[services.keystore]` section to point to your credentials file, according to [this section](https://github.com/google/tink/blob/9bc2667963e20eb42611b7581e570f0dddf65a2b/docs/KEY-MANAGEMENT.md#credentials).
-4. Win!
+The vision for the project is laid out in [this document](doc/service/vision.md).
 
-To use a randomly generated encryption key (NOT RECOMMENDED FOR ANY PRODUCTION ENVIRONMENT):
-1. Make sure that `master_key_uri` and `kms_credentials_path` of the `[services.keystore]` section are not set.
+The project follows a proposal-based improvement format called [SIPs, outlined here](sip/README.md).
 
-Note that at this time, we do not currently support rotating the master key.
+Please [join Discord](https://discord.com/invite/tbd), or open an [issue](https://github.com/TBD54566975/ssi-service/issues) if you are interested in helping shape the future of the
+project.
 
-### Steps for SSI-Service to consume its configuration:
-1. On startup: SSI-Service loads default values into the SSIServiceConfig
-2. Checks for a TOML config file:
-- If exists...load toml file
-- If does not exist...it uses a default config defined in the code inline
-3. Finally, it loads the config/.env file and adds the env variables defined in this file to the final SSIServiceConfig
+### API Documentation
 
-### Authentication and Authorization
+API documentation is generated using [Swagger](https://swagger.io/). The most recent
+docs [can be found here](doc/swagger.yaml).
 
-The ssi server uses the Gin framework from Golang, which allows various kinds of middleware. Look in `pkg/middleware/Authentication.go` and `pkg/middleware/Authorization.go` for details on how you can wire up authentication and authorization for your use case.
+When running the service you can find API documentation at: `http://localhost:8080/swagger/index.html`
 
-## Pre-built images to use
+**Note:** Your port may differ; swagger docs are hosted on the same endpoint as the ssi service itself.
 
-There are pre-build images built by github actions on each merge to the main branch, which you can access here:
-https://github.com/orgs/TBD54566975/packages?repo_name=ssi-service
+### How To's
 
+We have a set of tutorials and how-to documents, instructing you on how to create a DID, issue your first credential,
+and more! The docs can be found [in our docs here](doc/README.md).
 
 ## Build & Test
 
+### Local Development
 This project uses [mage](https://magefile.org/), please
 view [CONTRIBUTING](https://github.com/TBD54566975/ssi-service/blob/main/CONTRIBUTING.md) for more information.
 
@@ -101,28 +72,61 @@ A utility is provided to run _clean, build, lint, and test_ in sequence with:
 mage cblt
 ```
 
+### Continuous Integration
+
+CI is managed via [GitHub Actions](https://github.com/TBD54566975/ssi-service/actions). Actions are triggered to run for
+each Pull Request, and on merge to `main`.
+You can run CI locally using a tool like [act](https://github.com/nektos/act).
+
 ## Deployment
 
 The service is packaged as a [Docker container](https://www.docker.com/), runnable in a wide variety of
 environments.
 
+There are pre-build images built by GitHub Actions on each merge to the `main` branch,
+which [you can access here](https://github.com/orgs/TBD54566975/packages?repo_name=ssi-service).
+
 [Docker Compose](https://docs.docker.com/compose/) is used for simplification and orchestration. To run
 the service, you can use the following command, which will start the service on port `8080`:
+
 ```shell
 mage run
 ```
 
 Or, you can run docker-compose yourself, building from source:
+
 ```shell
 cd build && docker-compose up --build
 ```
 
 To use the pre-published images:
+
 ```shell
 cd build && docker-compose up -d
 ```
 
-## Health and Readiness Checks
+## Using the Service
+
+### Configuration
+
+Managed via:
+[TOML](https://toml.io/en/) [file](config/dev.toml). Configuration documentation and sample config
+files [can be found here](config/README.md).
+
+There are sets of configuration values for the server (e.g. which port to listen on), the services (e.g. which database
+to use),
+and each service. Each service may define specific configuration, such as which DID methods are enabled for the DID
+service.
+
+More information on configuration can be found in the [configuration section of our docs](doc/README.md).
+
+### Authentication and Authorization
+
+The SSI server uses the [Gin framework](https://github.com/gin-gonic/gin), which allows various kinds of middleware.
+Look in `pkg/middleware/Authentication.go` and `pkg/middleware/Authorization.go` for details on how you can wire up
+authentication and authorization for your use case.
+
+### Health and Readiness Checks
 
 Note: port 3000 is used by default, specified in `config.toml`, for the SSI Service process. If you're running
 via `mage run` or docker compose, the port to access will be `8080`.
@@ -157,45 +161,6 @@ Run to check if all services are up and ready (credential, did, and schema):
 }
 ```
 
-## Continuous Integration
-
-CI is managed via [GitHub Actions](https://github.com/TBD54566975/ssi-service/actions). Actions are triggered to run
-for each Pull Request, and on merge to `main`. You can run CI locally using a tool
-like [act](https://github.com/nektos/act).
-
-## API Documentation
-You can find all HTTP endpoints by checking out the swagger docs at: `http://localhost:8080/swagger/index.html`
-
-Note: Your port may differ; swagger docs are hosted on the same endpoint as the ssi service itself.
-
-## What's Supported?
-- [x] [DID Management](https://www.w3.org/TR/did-core/)
-  - [x] [did:key](https://w3c-ccg.github.io/did-method-key/)
-  - [x] [did:web](https://w3c-ccg.github.io/did-method-web/)
-  - [x] [did:ion](https://identity.foundation/ion/) _Note: updates not yet supported_
-  - [x] [did:pkh](https://w3c-ccg.github.io/did-method-pkh/) _Resolution only_
-  - [x] [did:peer](https://identity.foundation/peer-did-method-spec/) _Resolution only_
-- [x] [Verifiable Credential Schema](https://w3c-ccg.github.io/vc-json-schemas/v2/index.html) Management
-- [x] [Verifiable Credential](https://www.w3.org/TR/vc-data-model) Issuance & Verification
-  - [x] Signing and verification with [JWTs](https://w3c.github.io/vc-jwt/)
-  - [ ] Signing and verification with [Data Integrity Proofs](https://w3c.github.io/vc-data-integrity/)
-- [x] Applying for Verifiable Credentials using [Credential Manifest](https://identity.foundation/credential-manifest/)
-- [x] Requesting, Receiving, and the Validation of Verifiable Claims
-  using [Presentation Exchange](https://identity.foundation/presentation-exchange/)
-- [x] Status of Verifiable Credentials using the [Status List 2021](https://w3c-ccg.github.io/vc-status-list-2021/)
-- [x] [DID Well Known Configuration](https://identity.foundation/.well-known/resources/did-configuration/) documents
-- [ ] Creating and managing Trust documents using [Trust Establishment](https://identity.foundation/trust-establishment/)
-
-## Vision, Features, and Development
-
-The vision for the project is laid out in [this document](doc/VISION.md).
-
-The project follows a proposal-based improvement format called [SIPs, outlined here.](sip/README.md).
-
-Please [join Discord](https://discord.com/invite/tbd),
-or open an [issue](https://github.com/TBD54566975/ssi-service/issues) if you are interested in helping shape the future of the project.
-
-
 ## Project Resources
 
 | Resource                                                                                   | Description                                                                   |

diff --git a/cmd/ssiservice/main.go b/cmd/ssiservice/main.go
@@ -30,13 +30,12 @@ import (
 // main godoc
 //
 //	@title			SSI Service API
-//	@description	{{.Desc}}
+//	@description	The Self Sovereign Identity Service: Managing DIDs, Verifiable Credentials, and more!
 //	@contact.name	TBD
 //	@contact.url	https://github.com/TBD54566975/ssi-service/issues
 //	@contact.email	[email protected]
 //	@license.name	Apache 2.0
 //	@license.url	http://www.apache.org/licenses/LICENSE-2.0.html
-//	@version		{{.SVN}}
 func main() {
 	logrus.Info("Starting up...")
 

diff --git a/config/README.md b/config/README.md
diff --git a/doc/README.md b/doc/README.md
@@ -1,11 +1,57 @@
+# Docs
+
+Home for all content related to the SSI Service.
 
 ## Service Documentation
 
-| Resource                                                                             | Description                                        |
-|--------------------------------------------------------------------------------------|----------------------------------------------------|
-| [Vision](https://github.com/TBD54566975/ssi-service/blob/main/doc/VISION.md)         | Describes the vision for the SSI Service           |
-| [Versioning](https://github.com/TBD54566975/ssi-service/blob/main/doc/VERSIONING.md) | Describes versioning practices for the SSI Service |
-| [Webhooks](https://github.com/TBD54566975/ssi-service/blob/main/doc/WEBHOOK.md)      | Describes how to use webhooks in the SSI Service   |
-| [Storage](https://github.com/TBD54566975/ssi-service/blob/main/doc/STORAGE.md)       | Describes alternatives for storage in SSI Service  |
+Service documentation is focused on explaining the "whys" and "hows" of the SSI Service. It is intended to be a
+resource for developers and users of the SSI Service.
+
+| Resource                                                                                     | Description                                       |
+|----------------------------------------------------------------------------------------------|---------------------------------------------------|
+| [Vision](https://github.com/TBD54566975/ssi-service/blob/main/doc/service/vision.md)         | Describes the vision for the service              |
+| [Versioning](https://github.com/TBD54566975/ssi-service/blob/main/doc/service/versioning.md) | Describes versioning practices for the service    |
+| [Webhooks](https://github.com/TBD54566975/ssi-service/blob/main/doc/service/webhook.md)      | Describes how to use webhooks in the service      |
+| [Features](https://github.com/TBD54566975/ssi-service/blob/main/doc/service/features.md)     | Features currently supported by the service       |
+
+## Service Improvement Proposals (SIPs)
+
+All feature proposal documents for the SSI Service follow a common format and are known as SSI Improvement Proposals or
+SIPs. SIPs [have their own documentation which can be found here](https://github.com/TBD54566975/ssi-service/blob/main/doc/sip/README.md)
+
+## Configuration
+
+There are a few ways to configure the service. There are a few choices you can make, including which database to use,
+which DID methods to enable, and which port to listen on. Read the docs below for more details!
+
+| Resource                                                                                                   | Description                            |
+|------------------------------------------------------------------------------------------------------------|----------------------------------------|
+| [TOML Config Files](https://github.com/TBD54566975/ssi-service/blob/main/doc/config/toml.md)                   | Describes how to use TOML config files |
+| [Using a Cloud Key Management Service](https://github.com/TBD54566975/ssi-service/blob/main/doc/config/kms.md) | Describes how to configure a KMS       |
+| [Storage](https://github.com/TBD54566975/ssi-service/blob/main/doc/service/storage.md)       | Describes alternatives for storage by the service |
+
+## API Documentation
+
+API documentation is generated using [Swagger](https://swagger.io/). The most recent API docs file [can be found here](doc/swagger.yaml), which can be pasted into the [Swagger Editor](https://editor.swagger.io/) for interaction.
+
+When running the service you can find API documentation at: `http://localhost:8080/swagger/index.html`
+
+**Note:** Your port may differ; swagger docs are hosted on the same endpoint as the ssi service itself.
+
+## How To's
+
+How to documentation is focused on explaining usage of the SSI Service. It is intended to be a resource for users of
+the SSI Service to get up to speed with its functionality.
+
+| Resource                                                                                                                                     | Description                                            |
+|----------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------|
+| [Creating a DID](https://github.com/TBD54566975/ssi-service/blob/main/doc/howto/credential.md)                                               | Get started with DID functionality                     |
+| [Creating a Schema](https://github.com/TBD54566975/ssi-service/blob/main/doc/howto/schema.md)                                                | Get started with schema functionality                  |
+| [Issuing a Credential](https://github.com/TBD54566975/ssi-service/blob/main/doc/howto/credential.md)                                         | Get started with credential issuance functionality     |
+| [Verify a Credential](https://github.com/TBD54566975/ssi-service/blob/main/doc/howto/verification.md)                                        | Get started with credential verification functionality |
+| [Revoke/Suspend a Credential](https://github.com/TBD54566975/ssi-service/blob/main/doc/howto/status.md)                                      | Get started with credential status functionality       |
+| [[TODO] Requesting and Verifying Credentials with Presentation Exchange](https://github.com/TBD54566975/ssi-service/issues/606)              | Get started with Presentation Exchange functionality   |
+| [[TODO] Accepting Applications for and Issuing Credentials using Credential Manifest](https://github.com/TBD54566975/ssi-service/issues/606) | Get started with Credential Manifest functionality     |
+| [[TODO] Creating a Well Known File for your DID](https://github.com/TBD54566975/ssi-service/issues/606)                                      | Get started with DID Well Known functionality          |