Initial architecture thoughts

docs/processes/client-auth.md

@@ -0,0 +1,68 @@
+# Client Authentication and Authorization
+
+## Overview
+
+The authentication and authorization process for ADRFlow ensures that users are properly authenticated and authorized to access repositories and Azure resources. This process supports both GitHub and Azure DevOps for repository management, using OAuth for authentication for RBAC authorization.
+
+## Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant CLI
+    participant GitHubOAuth
+    participant AzureDevOpsOAuth
+    participant AzureADOAuth
+    participant RepositoryAPI
+    participant AzureResourceAPI
+
+    User->>CLI: Initiate CLI Command
+    CLI->>CLI: Determine Repository Platform (GitHub/Azure DevOps)
+
+    alt GitHub Repository
+        CLI->>GitHubOAuth: Authenticate User via OAuth
+        GitHubOAuth-->>CLI: Return Access Token
+        CLI->>RepositoryAPI: Make Authenticated Request (with Access Token)
+    else Azure DevOps Repository
+        CLI->>AzureDevOpsOAuth: Authenticate User via OAuth
+        AzureDevOpsOAuth-->>CLI: Return Access Token
+        CLI->>RepositoryAPI: Make Authenticated Request (with Access Token)
+    end
+
+    CLI->>AzureADOAuth: Authenticate User via OAuth (for Azure resources)
+    AzureADOAuth-->>CLI: Return Access Token
+    CLI->>AzureResourceAPI: Make Authenticated Request (with Access Token)
+    AzureResourceAPI-->>CLI: Return Data
+    CLI-->>User: Display Result
+```
+
+## Steps in the Process
+
+1. **Initiate CLI Command**:
+   - The user initiates a command in the Command Line Interface (CLI).
+2. **Determine Repository Platform**:
+   - The CLI determines whether the repository is hosted on GitHub or Azure DevOps based on the local repository information (remote URL).
+3. **Authenticate with Repository Pattern**:
+   - **GitHub Repository**:
+     - The CLI initiates the GitHub OAuth flow to authenticate the user.
+     - GitHub returns an access token to the CLI.
+     - The CLI uses the access token to make authenticated requests to the GitHub  API.
+   - **Azure DevOps Repository**:
+     - The CLI initiates the Azure DevOps OAuth flow to authenticate the user.
+     - Azure DevOps returns an access token to the CLI.
+     - The CLI uses the access token to make authenticated requests to the Azure DevOps API.
+4. **Authenticate with Azure for Application Resources**
+   - The CLI initiates the Azure Active Directory (AAD) OAuth flow to authenticate the user for access Azure resources.
+   - Azure AD returns an access token to the CLI.
+   - The CLI uses the access token to make authenticated requests to Azure Resource APIs (e.g. Cosmos DB, Azure App Configuration).
+5. **Authorization with RBAC**:
+   - For repository access, the CLI CLI enforces RBAC based on the user's role in GitHub or Azure DevOPs.
+   - For Azure resources, the CLI enforces RBAC based on the user's role in Microsoft Entra ID.
+   - The CLI makes authenticated requests to the respective APIs (Repository API, Azure Resource API) based on the user's permissions.
+6. **Return Data**:
+   - The respective API (Repository API, Azure Resource API) returns the requested data to the CLI.
+   - The CLI displays the result to the user.
+
+## Conclusion
+
+The **Client Authentication and Authorization** process for ADRFlow ensures secure access to repositories and Azure resources. By leveraging OAuth for authentication and RBAC for authorization, ADRFlow provides a consistent and scalable approach to managing user permissions across GitHub, Azure DevOps, and Azure. This process flow enables user to seamlessly interact with ADRFlow while ensuring that access controls are enforced based on their roles.

docs/processes/create-adr.md

@@ -0,0 +1,76 @@
+# Create ADR
+
+## Overview
+
+The Create ADR process in **ADRFlow** is designed to streamline the creation of Architecture Decision Records (ADRs) by automating the generation of unique identifiers, populating initial metadata, and creating the markdown document. This process ensures consistency and efficiency while integrating seamlessly with users' local repositories and the central database.
+
+## Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant CLI
+    participant API
+    participant CosmosDB
+
+    User->>CLI: create-adr
+    CLI->>User: Prompt for details
+    User->>CLI: Provide details (app name, adr name, author)
+    CLI->>CLI: Create branch in local repository
+    CLI->>API: Create ADR (app name, adr name, author)
+    API->>CosmosDB: Generate ADR number and store metadata
+    CosmosDB-->>API: Return ADR number and metadata
+    API-->>CLI: Return ADR number and metadata
+    CLI->>CLI: Generate markdown file
+    CLI-->>User: Display confirmation and file location
+```
+
+## Steps in the Process
+
+1. **Initiate Creation**:
+   - **User Input**: The user initiates the process by running the `create-adr` command in the Command Line Interface (CLI).
+   - **Details**: The CLI prompts the user to provide essential details: application/microservice name, ADR name, and author name.
+2. **Create Branch**:
+   - **Branch Creation**: The CLI creates a new branch in the target application/microservice repository on the local machine. The branch could follow a convention such as `adr/<adr_number>_<adr_name>`.
+
+> [!NOTE]
+>
+> The branch creation process is based on the current working directory where the CLI command is executed.
+
+3. **Generate ADR Number**:
+
+- **API Call**: The CLI sends a request to the `Create ADR` API endpoint, passing the provided details.
+- **Metadata Generation**: The API generates a unique ADR number and creates initial metadata.
+- **API Response**: The API responds to the CLI with the ADR number and initial metadata.
+
+1. **Create Markdown File**:
+   - **Template Usage**: The CLI generates the initial ADR markdown document using a predefined template.
+   - **Populate Content**: The CLI populates the markdown document with the ADR number,AR name, author name, initial status (Proposed), and other metadata.
+   - **Save File**: The CLI saves the markdown file in the local repository.
+2. **Store Metadata**:
+   - **Database Update**: The API stores the initial ADR metadata in Azure Cosmos DB Gremlin, including the status history and relationships.
+3. **Output**:
+   - **Confirmation**: The CLI confirms the successful creation of the ADR and displays the location of the markdown file to the user.
+
+## Component Interactions
+
+- **Command Line Interface (CLI)**:
+  - Initiates the create ADR process by collecting necessary details from the user.
+  - Creates a new branch in the local repository.
+  - Interacts with the `Create ADR` API endpoints to generate an ADR number and receive initial metadata.
+  - Generates and saves the ADR markdown document in the new branch of the local repository.
+  - Displays a confirmation message to the user.
+- **API**:
+  - Receives requests from the CLI to create a new ADR.
+  - Generates a unique ADR number and creates initial metadata.
+  - Stores the ADR metadata in Azure Cosmos DB Gremlin.
+  - Returns the ADR number and metadata to the CLI.
+- **Azure Cosmos DB Gremlin**:
+  - Sores the ADR metadata, including relationships and status history, to ensure traceability and relationship analysis.
+  - Provides confirmation of storage to the API.
+
+## Conclusion
+
+The **Create ADR** process in **ADRFlow** is designed to be straightforward and efficient, leveraging a combination of CLI and API interactions. By automating key steps, such as generating unique ADR number and populating initial metadata, ADRFlow ensures consistency and reduces the effort required to create and manage ADRs. This process provides a solid foundation for managing architectural decisions, enabling teams to focus on the content and quality of their decisions rather than the mechanics of record-keeping.
+
+By following this process, users can quickly and easily create new ADRs, ensuring that their architectural decisions are well-documented, traceable, and integrated into their local repositories. The flexibility of the API-based approach allows for future expansion, including the potential addition of web and desktop interfaces.

docs/processes/get-adr-details.md

@@ -0,0 +1,54 @@
+# Get ADR Details
+
+The **Get ADR Details** process in **ADRFlow** allows users to retrieve detailed information about a specific Architecture Decision Record (ADR). This process fetches metadata, status history, and markdown content for the ADR, providing a comprehensive view of the decision.
+
+## Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant CLI
+    participant API
+    participant CosmosDB
+
+    User->>CLI: get-adr <adr_id>
+    CLI->>API: Get ADR <adr_id>
+    API->>CosmosDB: Fetch ADR metadata <adr_id>
+    CosmosDB-->>API: Return ADR metadata
+    API-->>CLI: Return ADR metadata and markdown content
+    CLI-->>User: Display ADR details
+```
+
+## Steps in the Process
+
+1. **Initiate Retrieval**:
+   - **User Input**: The user initiates the process by running the `get-adr` command in the Command Line Interface (CLI).
+   - **ADR Id**: The user provides the ADR identifier as input.
+2. **Retrieve Metadata**:
+   - **API Call**: The CLI sends a request to the `Get ADR` API endpoint with the provided ADR Id.
+   - **Database Query**: The API retrieves the ADR metadata from Azure Cosmos DB Gremlin.
+3. **Fetch Markdown Content**:
+   - **Optional**: The API fetches the markdown content from the stored location (e.g., a file repository or a version control system).
+4. **Return Details**:
+   - **API Response**: The API responds to the CLI with the retrieved ADR metadata and markdown content.
+5. **Display Metadata**:
+   - **Output**: The CLI displays the detailed ADR information, including metadata, status history, and markdown content, to the user.
+
+## Component Interactions
+
+- **Command Line Interface (CLI)**:
+  - Initiates the get ADR details process by accepting the ADR ID from the user.
+  - Sends a request to the `Get ADR` API endpoint to retrieve ADR details.
+  - Displays the retrieved information to the user.
+- **API**:
+  - Receives requests from the CLI to get ADR details.
+  - Fetches the ADR metadata from Azure Cosmos DB Gremlin.
+  - Fetches the markdown content from the stored location.
+  - Responds to the CLI with the retrieved ADR details.
+- **Azure Cosmos DB Gremlin**:
+  - Stores the ADR metadata and status history.
+  - Provides the metadata when queried by the API.
+
+## Conclusion
+
+The **Get ADR Details** process in ADRFlow ensures that users can easily access detailed information about specific ADRs. By fetching metadata and markdown content from the central database, users gain a comprehensive view of the architectural decisions, including their context, status history, and content. This process facilitates better understanding and traceability of decisions, supporting effective collaboration and decision-making within the team.

docs/processes/list-adrs.md

@@ -0,0 +1,52 @@
+# List ADRs
+
+## Overview
+
+The **List ADRs** process in **ADRFlow** allows users to retrieve a list of Architecture Records (ADRs) based on various criteria such as status, date, author, or application/microservice. This process provides a comprehensive view of available ADRs, facilitating quick access and efficient management.
+
+## Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant CLI
+    participant API
+    participant CosmosDB
+
+    User->>CLI: list-adrs
+    CLI->>API: List ADRs (optional filters)
+    API->>CosmosDB: Fetch ADRs with filters (if provided)
+    CosmosDB-->>API: Return list of ADRs
+    API-->>CLI: Return list of ADRs
+    CLI-->>User: Display list of ADRs
+```
+
+## Steps in the Process
+
+1. **Initiate Listing**:
+   - **User Input**: The user initiates the process by running the `list-adrs` command in the Command Line Interface (CLI).
+   - **Optional Filters**: The user can provide optional filters such as status, date, author, or application/microservice.
+2. **Retrieve ADRs**:
+   - **API Call**: The CLI sends a request to the `List ADRs` API endpoint, passing the optional filters if provided.
+   - **Database Query**: The API queries Azure Cosmos DB Gremlin to fetch ADRs that match the provided filters.
+3. **Return ADRs**:
+   - **API Response**: The API responds to the CLI with the list of ADRs that match the criteria.
+4. **Display ADRs**: The CLI displays the list of ADRs, providing brief summaries for each ADR.
+
+## Component Interactions
+
+- **Command Line Interface (CLI)**:
+  - Initiates the list ADRs process by accepting optional filters from the user.
+  - Sends a request to the `List ADRs` API endpoint to retrieve ADRs based on the provided criteria.
+  - Displays the list of ADRs to the user.
+- **API**:
+  - Receives requests from the CLI to list ADRs.
+  - Queries Azure Cosmos DB Gremlin to fetch ADRs, that match the provided filters.
+  - Responds to the CLI with the list of ADRs.
+- **Azure Cosmos DB Gremlin**:
+  - Stores ADR metadata, including status, date, author, and application/microservice information.
+  - Provides the list of ADRs when queried by the API, applying any filters if specified.
+
+## Conclusion
+
+The **List ADRs** process in **ADRFlow** enable users to efficiently retrieve and view a list of Architecture Decision Records based on various criteria. By querying the central database and applying optional filters, user can quickly access the ADRs relevant to their needs. This process enhances the manageability and accessibility of ADRs, supporting better decision-making and organization with the team.

docs/processes/upload-adr.md

@@ -0,0 +1,45 @@
+# Upload ADR
+
+## Overview
+
+The **Upload ADR** process in **ADRFlow** allows users to upload newly created ADRs or update existing ADRs. This process ensures that any changes or new additions are synchronized with the central database, maintaining up-to-date and accurate records.
+
+## Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant CLI
+    participant API
+    participant CosmosDB
+
+    User->>CLI: upload-adr <file_path>
+    CLI->>API: Upload ADR (new/update) with metadata
+    API->>CosmosDB: Store/update ADR metadata
+    CosmosDB-->>API: Confirm storage/update
+    API-->>CLI: Return success message
+    CLI-->>User: Display confirmation message
+```
+
+## Steps in the Process
+
+1. **Initiate Upload**
+   - **User Input**: The user initiates the process by running the `upload-adr` command in the Command Line Interface (CLI).
+   - **File Path**: The user provides the file path of the ADR markdown document.
+2. **Extract Metadata**:
+   - **Metadata Extraction**: The CLI extracts metadata from the provided markdown document, such as ADR ID, title, status, date, author, and content.
+3. **Determine Action**:
+   - **New or Update**: The CLI checks if the ADR is new or an updated based on the ADR Id.
+     - **New ADR**: If the ADR ID does not exist in the database, it is treated as a new ADRs.
+     - **Update ADR**: If the ADR ID exists, it is treated as an update to an existing ADR.
+4. **Upload Metadata**:
+   - **API Call**: The CLI sends a request to the `Upload ADR` API endpoint, including the extracted metadata and content.
+   - **Store Metadata**: The API stores the new ADR metadata or updates the existing ADR metadata in Azure Cosmos DB Gremlin.
+5. **Return Confirmation**:
+   - **Command Line Interface (CLI)**:
+     - Initiates the upload ADR process by accessing the file path from the user.
+     - Extracts metadata fromt he provided markdown document.
+     - Determines if the ADR is new or an updated based on the ADR ID.
+     - Sends a request to the `upload ADR` API endpoint to store or update the ADR metadata.
+     - Displays a confirmation message to the user.
+   - **API**: