Update docs

Signed-off-by: Ian Costanzo <[email protected]>

CODE_OF_CONDUCT.md

@@ -0,0 +1,166 @@
+# [Hyperledger Code of Conduct](https://wiki.hyperledger.org/community/hyperledger-project-code-of-conduct)
+
+Hyperledger is a collaborative project at The Linux Foundation. It is an open-source and open
+community project where participants choose to work together, and in that process experience
+differences in language, location, nationality, and experience. In such a diverse environment,
+misunderstandings and disagreements happen, which in most cases can be resolved informally. In rare
+cases, however, behavior can intimidate, harass, or otherwise disrupt one or more people in the
+community, which Hyperledger will not tolerate.
+
+A **Code of Conduct** is useful to define accepted and acceptable behaviors and to promote high
+standards of professional practice. It also provides a benchmark for self evaluation and acts as a
+vehicle for better identity of the organization.
+
+This code (**CoC**) applies to any member of the Hyperledger community – developers, participants in
+meetings, teleconferences, mailing lists, conferences or functions, etc. Note that this code
+complements rather than replaces legal rights and obligations pertaining to any particular
+situation.
+
+## Statement of Intent
+
+Hyperledger is committed to maintain a **positive** [work environment](#work-environment). This
+commitment calls for a workplace where [participants](#participant) at all levels behave according
+to the rules of the following code. A foundational concept of this code is that we all share
+responsibility for our work environment.
+
+## Code
+
+1. Treat each other with [respect](#respect), professionalism, fairness, and sensitivity to our many
+   differences and strengths, including in situations of high pressure and urgency.
+
+2. Never [harass](#harassment) or [bully](#workplace-bullying) anyone verbally, physically or
+   [sexually](#sexual-harassment).
+
+3. Never [discriminate](#discrimination) on the basis of personal characteristics or group
+   membership.
+
+4. Communicate constructively and avoid [demeaning](#demeaning-behavior) or
+   [insulting](#insulting-behavior) behavior or language.
+
+5. Seek, accept, and offer objective work criticism, and [acknowledge](#acknowledgement) properly
+   the contributions of others.
+
+6. Be honest about your own qualifications, and about any circumstances that might lead to conflicts
+   of interest.
+
+7. Respect the privacy of others and the confidentiality of data you access.
+
+8. With respect to cultural differences, be conservative in what you do and liberal in what you
+   accept from others, but not to the point of accepting disrespectful, unprofessional or unfair or
+   [unwelcome behavior](#unwelcome-behavior) or [advances](#unwelcome-sexual-advance).
+
+9. Promote the rules of this Code and take action (especially if you are in a
+   [leadership position](#leadership-position)) to bring the discussion back to a more civil level
+   whenever inappropriate behaviors are observed.
+
+10. Stay on topic: Make sure that you are posting to the correct channel and avoid off-topic
+    discussions. Remember when you update an issue or respond to an email you are potentially
+    sending to a large number of people.
+
+11. Step down considerately: Members of every project come and go, and the Hyperledger is no
+    different. When you leave or disengage from the project, in whole or in part, we ask that you do
+    so in a way that minimizes disruption to the project. This means you should tell people you are
+    leaving and take the proper steps to ensure that others can pick up where you left off.
+
+## Glossary
+
+### Demeaning Behavior
+
+is acting in a way that reduces another person's dignity, sense of self-worth or respect within the
+community.
+
+### Discrimination
+
+is the prejudicial treatment of an individual based on criteria such as: physical appearance, race,
+ethnic origin, genetic differences, national or social origin, name, religion, gender, sexual
+orientation, family or health situation, pregnancy, disability, age, education, wealth, domicile,
+political view, morals, employment, or union activity.
+
+### Insulting Behavior
+
+is treating another person with scorn or disrespect.
+
+### Acknowledgement
+
+is a record of the origin(s) and author(s) of a contribution.
+
+### Harassment
+
+is any conduct, verbal or physical, that has the intent or effect of interfering with an individual,
+or that creates an intimidating, hostile, or offensive environment.
+
+### Leadership Position
+
+includes group Chairs, project maintainers, staff members, and Board members.
+
+### Participant
+
+includes the following persons:
+
+- Developers
+- Member representatives
+- Staff members
+- Anyone from the Public partaking in the Hyperledger work environment (e.g. contribute code,
+  comment on our code or specs, email us, attend our conferences, functions, etc)
+
+### Respect
+
+is the genuine consideration you have for someone (if only because of their status as participant in
+Hyperledger, like yourself), and that you show by treating them in a polite and kind way.
+
+### Sexual Harassment
+
+includes visual displays of degrading sexual images, sexually suggestive conduct, offensive remarks
+of a sexual nature, requests for sexual favors, unwelcome physical contact, and sexual assault.
+
+### Unwelcome Behavior
+
+Hard to define? Some questions to ask yourself are:
+
+- how would I feel if I were in the position of the recipient?
+- would my spouse, parent, child, sibling or friend like to be treated this way?
+- would I like an account of my behavior published in the organization's newsletter?
+- could my behavior offend or hurt other members of the work group?
+- could someone misinterpret my behavior as intentionally harmful or harassing?
+- would I treat my boss or a person I admire at work like that ?
+- Summary: if you are unsure whether something might be welcome or unwelcome, don't do it.
+
+### Unwelcome Sexual Advance
+
+includes requests for sexual favors, and other verbal or physical conduct of a sexual nature, where:
+
+- submission to such conduct is made either explicitly or implicitly a term or condition of an
+  individual's employment,
+- submission to or rejection of such conduct by an individual is used as a basis for employment
+  decisions affecting the individual,
+- such conduct has the purpose or effect of unreasonably interfering with an individual's work
+  performance or creating an intimidating hostile or offensive working environment.
+
+### Workplace Bullying
+
+is a tendency of individuals or groups to use persistent aggressive or unreasonable behavior (e.g.
+verbal or written abuse, offensive conduct or any interference which undermines or impedes work)
+against a co-worker or any professional relations.
+
+### Work Environment
+
+is the set of all available means of collaboration, including, but not limited to messages to
+mailing lists, private correspondence, Web pages, chat channels, phone and video teleconferences,
+and any kind of face-to-face meetings or discussions.
+
+## Incident Procedure
+
+To report incidents or to appeal reports of incidents, send email to Mike Dolan
+([email protected]) or Angela Brown ([email protected]). Please include any
+available relevant information, including links to any publicly accessible material relating to the
+matter. Every effort will be taken to ensure a safe and collegial environment in which to
+collaborate on matters relating to the Project. In order to protect the community, the Project
+reserves the right to take appropriate action, potentially including the removal of an individual
+from any and all participation in the project. The Project will work towards an equitable resolution
+in the event of a misunderstanding.
+
+## Credits
+
+This code is based on the
+[W3C’s Code of Ethics and Professional Conduct](https://www.w3.org/Consortium/cepc) with some
+additions from the [Cloud Foundry](https://www.cloudfoundry.org/)‘s Code of Conduct.

CONTRIBUTING.md

@@ -0,0 +1,14 @@
+## How to contribute
+
+You are encouraged to contribute to the repository by **forking and submitting a pull request**.
+
+For significant changes, please open an issue first to discuss the proposed changes to avoid re-work.
+
+(If you are new to GitHub, you might start with a [basic tutorial](https://help.github.com/articles/set-up-git) and check out a more detailed guide to [pull requests](https://help.github.com/articles/using-pull-requests/).)
+
+Pull requests will be evaluated by the repository guardians on a schedule and if deemed beneficial will be committed to the `main` branch. Pull requests should have a descriptive name, include an summary of all changes made in the pull request description, and include unit tests that provide good coverage of the feature or fix. A Continuous Integration (CI) pipeline is executed on all PRs before review and contributors are expected to address all CI issues identified. Where appropriate, PRs that impact the
+end-user and developer demos in the repo should include updates or extensions to those demos to cover the new capabilities.
+
+If you would like to propose a significant change, please open an issue first to discuss the work with the community.
+
+Contributions are made pursuant to the Developer's Certificate of Origin, available at [https://developercertificate.org](https://developercertificate.org), and licensed under the Apache License, version 2.0 (Apache-2.0).

README.md

@@ -1,19 +1,33 @@
 # traction
+
 Hyperledger Aries Traction - a digital wallet solution for organizations. This project space will be a rewrite of the Business Partner Agent with multitenancy, cloud native architecture and Open APIs.
 
+Traction provides a service layer to manage Aries agent instances in a multi-tenant aca-py deployment, and provides some value-add services for using aca-py functions such as setting up issuer agents, and issuing and verifying credentials.  Future functionality could include machine-readable governance, etc.
+
+## Running traction
+
+[Scripts](./scripts/README.md)  
+
+Docker Compose files for spinning up local instances of Traction and the Showcase application.  	
+
+## Deploying Traction
+
 [Charts](./charts/README.md) 
-	
+    
 Helm charts for deploying Traction, Showcase and Endorser to Openshift.  
-
-[Scripts](./scripts/README.md)  
 
-Docker Compose files for spinning up local instances of Traction and the Showcase application.  
-
-
+## Developing traction
+
+[Architecture](./docs/ARCHITECTURE.md)
+
+Overview of the traction architecture.
+
 [Traction](./services/traction/README.md)  
 
 Source code for Traction API.  
 
 [Traction Showcase/Demo](./services/showcase/README.md)  
 
-Source code for Traction Showcase/Demo application.  
+Source code for Endorser controller application.
+
+[Endorser](./services/endorser/README.md)

docs/ARCHITECTURE.md

@@ -0,0 +1,60 @@
+# traction architecture
+
+Traction provides a service layer to manage Aries agent instances in a multi-tenant aca-py deployment, and provides some value-add services for using aca-py functions such as setting up issuer agents, and issuing and verifying credentials.  Future functionality could include machine-readable governance, etc.
+
+Traction is built using open-source frameworks such as [FastAPI](https://fastapi.tiangolo.com/) to build and manage web services, [sqlalchemy](https://www.sqlalchemy.org/) to manage database access and [pydantic](https://pydantic-docs.helpmanual.io/) to support data validation.
+
+## Architecture Overview
+
+The below picture shows the main traction components:
+
+![traction architecture](./assets/architecture.png "traction architecture")
+
+- Aca-py agent - Aca-py provides a multi-tenant Aries agent that allows a manager (called an "Innkeeper") to create and manage Aries agents ("tenants") for different line-of-business ("LOB") applications.  Each tenant agent is secure and independant, managed by the business owner, and controlled (via traction) by the owner's LOB application.
+- Back End - traction maintains a database for the Innkeeper and for each tenant to store value-add information, augmenting the information stored by Aca-py.  Traction stores information about connected agents, tenant status (such as whether they are an issuer), any inflight or workflows (such as issued credential) to simplify LOB integration with Aries agents and protocols.
+- Traction Service - A set of secure web services that the Innkeeper and tenants use to interact with their Aca-py agent, and with other connected agents using Aries protocols.  Traction provides a separate set of services for Innkeepers and tenants (each set of services is secured for the appropriate users), as well as providing "wrapper" (secure) access to Aca-py functions that are outside of traction's scope (such as simple ledger lookups).
+- Front End - Traction provides a swagger interface for each set of services, to allow developers or evaluators to interact with traction in a simple, browser-based manner.  Traction also provides a demonstration "Showcase" application to illustrate how a set of Aries users can interact using traction agents.
+
+## Communication between Traction and LOB
+
+Traction provides a set of web services that the tenant LOB can call.  Traction also provides web hooks to which can notify the tenant LOB of any events which the LOB needs to respond to (or, for example, the completion of workflows that the LOB is dependant on).  The tenant can provide a custom endpoint for their LOB (the LOB needs to expose a web service that traction can call) and can subscribe to events of interest.  Traction can forward web hooks received from aca-py, and can provides web hooks for higher-level "business" events.  It is expected that an LOB will typically subscribe to the traction "business" events, but may be interested in a sub-set of the aca-py web hooks.
+
+## Security
+
+Front end applications have to authenticate to be able to call traction services.
+
+For the innkeeper, traction (currently) supports a single ID and password (this will likely change in a future version) - the front end app has to call a `/token` endpoint to retrieve a JWT, and then must provide the JWT for each service call.  For a tenant, they have to provide their wallet_id and wallet_key to a `/token` endpoint to get a JWT (specific to their wallet) which they have to provide with each service call.  (Note that the tenant is expected to store their wallet_id and wallet_key, there is no way to retrieve the wallet_key once their tenant wallet has been created.)
+
+Web hook callbacks form traction to the tenant's LOB application are secured using an API key (provided by the tenant).
+
+Service calls between traction and aca-py are secured by API keys (one for calls to aca-py and one for webhook callbacks from aca-py to traction) and - for tenant wallets - the tenant's bearer token (derived from their JWT).  (This security model is defined by aca-py.)
+
+The tenant's wallet is encrypted using their wallet_key (implemented by indy-sdk or aries-askar, depending on the aca-py configuration).
+
+## Traction code structure
+
+Traction code is organized using the following structure:
+
+```
+/services/traction
+   |
+   |-----> acapy_client   - service and model classes for calling aca-py
+   |
+   |-----> acapy_wrapper  - "wrapper" services to allow tenants to access aca-py directly (using traction's integrated security)
+   |
+   |-----> api
+   |    |
+   |    |-----> core      - core utility classes
+   |    |
+   |    |-----> db        - database model and accessor classes ("repositories")
+   |    |
+   |    |-----> endpoints - traction service endpoints and dependencies (models, etc)
+   |    |
+   |    |-----> services  - common services (typically used by multiple endpoints)
+   |
+   |-----> tests          - unit and integration tests
+```
+
+In general the dependencies are from `endpoints -> services -> db`, and `core` classes are used everywhere.
+
+See the [traction developer](../services/traction/README.md) documents for details on implementing each component.

scripts/README.md

@@ -9,8 +9,9 @@
 2. bring up traction
 
 ```sh
- cp .env-example .env.local
- docker-compose up
+cp .env-example .env.local
+docker-compose build
+docker-compose up
 ```
 
 ### stop
@@ -43,13 +44,12 @@ docker-compose up traction-agent
 docker-compose down traction-agent -v --remove-orphans
 ```
 
+#### start with showcase app
+This will start up traction (database, agent, endorser and api) and a showcase app (with its own database).
 
- #### start with showcase app
- This will start up traction (database, agent, endorser and api) and a showcase app (with its own database).
-
- ```sh
- docker-compose -f docker-compose.yml -f docker-compose.showcase.yml up
- ```
+```sh
+docker-compose -f docker-compose.yml -f docker-compose.showcase.yml up
+```
 
 ##### teardown