Add docs/structures on adapters and contributing

docs/adapters/broker/index.md

@@ -0,0 +1,2 @@
+# Brokers
+

docs/adapters/broker/redis.md

@@ -0,0 +1,2 @@
+# Redis
+

docs/adapters/cache/index.md

@@ -0,0 +1,2 @@
+# Caches
+

docs/adapters/cache/redis.md

@@ -0,0 +1,2 @@
+# Redis
+

docs/adapters/repository/elasticsearch.md → docs/adapters/database/elasticsearch.md

@@ -14,8 +14,11 @@ settings = "{'number_of_shards': 3}"
 
 Additional options for finer control:
 
-### namespace_prefix =IE${lasticsearch instance are prefixed with the specified stri}norexample, if the namespace prefix is `prod`, the index for aggregate
-`Person` will be `prod-person`.
+### NAMESPACE_PREFIX
+
+Elasticsearch instance are prefixed with the specified string. For example, if
+the namespace prefix is `prod`, the index for aggregate `Person` will be
+`prod-person`.
 
 ### NAMESPACE_SEPARATOR
 

docs/adapters/database/index.md

@@ -0,0 +1,2 @@
+# Databases
+

docs/adapters/database/postgresql.md

@@ -0,0 +1,2 @@
+# PostgreSQL
+

docs/adapters/database/redis.md

@@ -0,0 +1,2 @@
+# Redis
+

docs/adapters/eventstore/index.md

@@ -0,0 +1,2 @@
+# Event Stores
+

docs/adapters/eventstore/message-db.md

@@ -0,0 +1,2 @@
+# Message DB
+

docs/adapters/index.md

@@ -0,0 +1,82 @@
+# Adapters
+
+A core tenet in Protean's philosophy is to separate the domain
+from the underlying infrastructure. It enables you to code
+and test models without worrying about technology and plug in a
+component when ready. This lets you delay your decision on technology
+until [the last responsible moment](https://blog.codinghorror.com/the-last-responsible-moment/).
+
+Protean's design is based on the [Ports and Adapters architecture](https://en.wikipedia.org/wiki/Hexagonal_architecture_(software)),
+also known as Hexagonal Architecture,
+allowing loosely coupled components that can be easily connected and swapped.
+
+**Ports** are abstract interfaces that define a specific type of interaction
+between the application and the outside world. They define a protocol that can
+be implemented by concrete technology implementations called adapters. 
+
+**Adapters** are the glue between the application and the outside world. They
+tailor the exchanges between the external technology and the ports that
+represent the requirements of the inside of the application.
+
+Protean exposes several ports with an array of built-in adapters for
+each port.
+
+## Database
+
+The [Database port](./database/index.md) defines the interface for interacting
+with persistent storage
+systems. It abstracts the underlying database technology, allowing Protean to
+support various databases without changing the core application logic.
+
+Current Implementations:
+
+- [PostgreSQL](./database/postgresql.md)
+- [Elasticsearch](./database/elasticsearch.md)
+- [Redis](./database/redis.md)
+
+## Broker
+
+The [Broker port](./broker/index.md) defines the interface for message brokers and pub/sub systems.
+It enables communication between different parts of the ecosystem via messages,
+facilitating asynchronous processing and decoupling.
+
+!!!note
+    Protean internally uses an Event Store that acts both as an event
+    storage mechanism as well as a message delivery mechanism within a Protean-based
+    application. Brokers are more focused on integration with other systems.
+
+Current Implementations:
+
+- [Redis](./broker/redis.md)
+
+## Cache
+
+The [Cache port](./cache/index.md) defines the interface for interacting with caching systems. It
+exposes APIs to temporarily store and retrieve data, improving application
+performance by reducing the need for repeated database access.
+
+Current Implementations:
+
+- [Redis](./cache/redis.md)
+
+## Event Store
+
+The [Event Store](./eventstore/index.md) port defines the interface for event sourcing and event store
+systems. It handles the storage and retrieval of events, which are the
+fundamental units of change in event-driven architectures. This port ensures
+that all state changes are recorded as a sequence of events, providing a
+complete audit trail and enabling features like event replay and temporal
+queries.
+
+Current Implementations:
+
+- [Message DB](./eventstore/message-db.md)
+
+!!!note
+    We are working on adding a comprehensive set of adapters to this list.
+    We welcome your contribution - head over to the section on
+    [contributing adapters](../community/contributing/adapters.md) for more
+    information.
+
+    You can sponsor an adapter if you want to fast-track its implemetation.
+    [Get in touch](mailto:[email protected]) with us for a discussion.

docs/community/contributing/adapters.md

@@ -0,0 +1 @@
+# Adapters

docs/community/contributing.md → docs/community/contributing/setup.md

@@ -1,4 +1,4 @@
-# Contribute to Protean
+# Code Enhancements
 
 Thank you for considering contributing to Protean!
 

docs/community/index.md

@@ -1,5 +1,10 @@
 # Community
 
-## Get Involved
+## Support questions
 
-[Contribute to Protean](contributing.md)
+## Reporting Issues
+
+## Contribute to Protean
+
+- [Submit enhancements](./contributing/setup.md)
+- [Build adapters](./contributing/adapters.md)

docs/glossary.md

@@ -1,13 +1,88 @@
+---
+hide:
+  - navigation
+---
+
+<!-- Show TOC on the left -->
+<style>
+    .md-sidebar--secondary {
+        order: 0;
+    }
+</style>
+
 # Glossary
 
+## Aggregate
+A cluster of domain objects that can be treated as a single unit. An aggregate always has one root entity.
+
+## Application Service
+A service that contains business logic and orchestrates operations across multiple aggregates or domains.
+
 ## Bounded Context
+A boundary within which a particular domain model is defined and applicable. It ensures clear separation and encapsulation of models.
 
-## Domain
+## Category
+A logical grouping of related streams. It can represent a business domain or a part of it.
 
-## Repository
+## Command
+An instruction to perform a specific action, often resulting in a change of state within the system.
+
+## Command Handler
+A component responsible for processing commands and invoking corresponding actions on aggregates or domain services.
+
+## Command Stream
+A sequence of commands associated with a specific context or aggregate, recorded for tracking and processing purposes.
+
+## Composition
+The act of assembling smaller components into a more complex structure, often used to construct aggregates or services.
+
+## CQRS
+Command Query Responsibility Segregation, a design pattern that separates read and write operations to optimize performance and scalability.
 
 ## Custom Repository
+A specialized repository that provides custom methods for accessing and manipulating aggregates or entities beyond the standard CRUD operations.
 
 ## DAO
+Data Access Object, a pattern that provides an abstract interface to some type of database or other persistence mechanism.
+
+## Domain
+The sphere of knowledge and activity around which the business logic of the application revolves.
+
+## Domain Service
+A service that contains domain logic not belonging to any specific entity or value object, often operating across multiple aggregates.
+
+## Entity
+An object that is defined primarily by its identity rather than its attributes.
+
+## Event
+A significant change in state that is captured and recorded, typically representing a historical fact within the system.
+
+## Event Handler
+A component responsible for reacting to events, often used to trigger subsequent actions or processes.
+
+## Event Sourcing
+A pattern in which state changes are logged as a sequence of immutable events, enabling reconstruction of past states by replaying these events.
+
+## Event Store Pattern
+A storage pattern designed to persist events and support event sourcing, providing mechanisms to append and retrieve events efficiently.
+
+## Event Stream
+A chronological sequence of events related to a specific aggregate or bounded context, used to replay and reconstruct state.
+
+## Identity
+A unique identifier for an entity or aggregate, ensuring its distinctness within the system.
+
+## Message
+A piece of data sent between components, often used for communication and triggering actions in event-driven architectures.
+
+## Projection
+A read-only view of data that is constructed by processing one or more event streams, used to support query operations.
+
+## Repository
+A mechanism for encapsulating storage, retrieval, and search behavior for aggregates or entities, typically abstracting the underlying data store.
+
+## Stream
+A continuous flow of data or events, often used to represent a series of related messages or state changes within the system.
 
-## Filtering
+## Value Object
+An immutable object that represents a descriptive aspect of the domain with no conceptual identity, defined only by its attributes.

docs/stylesheets/extra.css

@@ -1,5 +1,6 @@
 [data-md-color-scheme="default"] {
   --md-primary-fg-color:        #1D3557;
+  --md-primary-bg-color-light:  #457B9D;
 
   --md-accent-fg-color:         #E76F51;
 
@@ -60,4 +61,8 @@ p a, article ul li a {
 /* Change nav title color */
 .md-nav__title {
   color: var(--md-primary-fg-color) !important;
+}
+
+.md-tabs {
+  background-color: var(--md-primary-bg-color-light);
 }

mkdocs.yml

@@ -2,6 +2,7 @@ site_name: Protean
 site_url: https://docs.proteanhq.com
 repo_name: proteanhq/protean
 repo_url: https://github.com/proteanhq/protean
+copyright: Copyright © 2019 - 2024 Subhash Bhushan
 
 theme:
   name: material
@@ -21,27 +22,27 @@ theme:
       name: Switch to light mode
 
   features:
+    - content.code.annotate
+    - content.code.copy
+    - content.code.select
+    - content.tabs.link
+    - content.tooltips
+    - navigation.expand
+    - navigation.footer
+    - navigation.indexes
     - navigation.instant
     - navigation.instant.prefetch
     - navigation.instant.progress
-    - navigation.tracking
+    - navigation.path
+    - navigation.prune
     - navigation.sections
     - navigation.tabs
     - navigation.tabs.sticky
-    - navigation.expand
-    - navigation.path
-    - navigation.prune
-    - navigation.indexes
-    - navigation.footer
-    - toc.follow
     - navigation.top
-    - search.suggest
+    - navigation.tracking
     - search.highlight
-    - content.tabs.link
-    - content.tooltips
-    - content.code.annotate
-    - content.code.copy
-    - content.code.select
+    - search.suggest
+    - toc.follow
 
 extra_css:
   - stylesheets/extra.css
@@ -214,8 +215,25 @@ nav:
   #   - examples/index.md
   #   - examples/quickstart.md
   # - faq.md
+  - Adapters:
+    - adapters/index.md
+    - Database:
+      - adapters/database/index.md
+      - adapters/database/postgresql.md
+      - adapters/database/elasticsearch.md
+      - adapters/database/redis.md
+    - Brokers:
+      - adapters/broker/index.md
+      - adapters/broker/redis.md
+    - Caches:
+      - adapters/cache/index.md
+      - adapters/cache/redis.md
+    - Event Stores:
+      - adapters/eventstore/index.md
+      - adapters/eventstore/message-db.md
   - glossary.md
   # - changelog.md
   - Community: 
     - community/index.md
-    - community/contributing.md
+    - community/contributing/setup.md
+    - community/contributing/adapters.md

src/protean/cli/docs.py

@@ -24,6 +24,6 @@ def callback():
 def preview():
     """Run a live preview server"""
     try:
-        subprocess.call(["mkdocs", "serve"])
+        subprocess.call(["mkdocs", "serve", "--dev-addr=0.0.0.0:8000"])
     except KeyboardInterrupt:
         pass