Organize contributor docs and establish ADR process and template (#29101)

.github/ISSUE_TEMPLATE/story.md

@@ -75,7 +75,7 @@ What else should contributors [keep in mind](https://fleetdm.com/handbook/compan
 ### Test plan
 <!-- Add detailed manual testing steps for all affected user roles. -->
 
-> Make sure to go through [the list](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/design-qa-considerations.md) and consider all events that might be related to this story, so we catch edge cases earlier.
+> Make sure to go through [the list](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/guides/ui/design-qa-considerations.md) and consider all events that might be related to this story, so we catch edge cases earlier.
 
 1. Step 1
 2. Step 2

.github/pull_request_template.md

@@ -5,7 +5,7 @@ If some of the following don't apply, delete the relevant line.
 <!-- Note that API documentation changes are now addressed by the product design team. -->
 
 - [ ] Changes file added for user-visible changes in `changes/`, `orbit/changes/` or `ee/fleetd-chrome/changes`.
-  See [Changes files](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Committing-Changes.md#changes-files) for more information.
+  See [Changes files](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/guides/committing-changes.md#changes-files) for more information.
 - [ ] Input data is properly validated, `SELECT *` is avoided, SQL injection is prevented (using placeholders for values in statements)
 - [ ] Added support on fleet's osquery simulator `cmd/osquery-perf` for new osquery data ingestion features.
 - [ ] If paths of existing endpoints are modified without backwards compatibility, checked the frontend/CLI for any necessary changes
@@ -17,7 +17,7 @@ If some of the following don't apply, delete the relevant line.
 - [ ] Added/updated automated tests
 - [ ] Manual QA for all new/changed functionality
 - For Orbit and Fleet Desktop changes:
-   - [ ] Make sure fleetd is compatible with the latest released version of Fleet (see [Must rule](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/fleetd-development-and-release-strategy.md)).
+   - [ ] Make sure fleetd is compatible with the latest released version of Fleet (see [Must rule](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/workflows/fleetd-development-and-release-strategy.md)).
    - [ ] Orbit runs on macOS, Linux and Windows. Check if the orbit feature/bugfix should only apply to one platform (`runtime.GOOS`).
    - [ ] Manual QA must be performed in the three main OSs, macOS, Windows and Linux.
    - [ ] Auto-update manual QA, from released version of component to new version (see [tools/tuf/test](../tools/tuf/test/README.md)).

CODEOWNERS

@@ -67,9 +67,18 @@ go.mod @fleetdm/go
 ##############################################################################################
 /docs                                           @rachaelshaw
 /docs/Contributing                              @lukeheath # « Contributing guidelines
+/docs/Contributing/architecture/mdm             @lukeheath @georgekarrv
+/docs/Contributing/architecture/orchestration   @lukeheath @sharon-fdm
+/docs/Contributing/architecture/software        @lukeheath @mostlikelee
+/docs/Contributing/product-groups/mdm           @lukeheath @georgekarrv
+/docs/Contributing/product-groups/orchestration  @lukeheath @sharon-fdm
+/docs/Contributing/product-groups/software      @lukeheath @mostlikelee
+/docs/Contributing/research/mdm                 @lukeheath @georgekarrv
+/docs/Contributing/research/orchestration       @lukeheath @sharon-fdm
+/docs/Contributing/research/software            @lukeheath @mostlikelee
 /docs/REST\ API/rest-api.md                     @rachaelshaw # « REST API reference documentation
-/docs/Contributing/API-for-contributors.md      @rachaelshaw # « Advanced / contributors-only API reference documentation
-/docs/Contributing/Audit-logs.md                @rachaelshaw # « Advanced / contributors-only audit log documentation
+/docs/Contributing/reference/API-for-contributors.md      @rachaelshaw # « Advanced / contributors-only API reference documentation
+/docs/Contributing/reference/Audit-logs.md                @rachaelshaw # « Advanced / contributors-only audit log documentation
 /schema                                         @eashaw # « Data tables (osquery/fleetd schema) documentation
 /render.yaml                                    @edwardsb
 

articles/chrome-os.md

@@ -20,7 +20,7 @@ By default, the hostname for a Chromebook host will be blank. The hostname can b
   - `usb_devices`: https://github.com/fleetdm/fleet/issues/12780
 
 ## Debugging ChromeOS
-To learn how to debug the Fleetd Chrome extension, visit [here](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Testing-and-local-development.md#fleetd-chrome-extension).
+To learn how to debug the Fleetd Chrome extension, visit [here](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/getting-started/testing-and-local-development.md#fleetd-chrome-extension).
 
 <meta name="category" value="guides">
 <meta name="authorGitHubUsername" value="zhumo">

articles/end-user-authentication.md

@@ -58,7 +58,7 @@ Fleet refreshes host details once per hour by default. As part of the refresh pr
 
 ## Sequence diagram
 
-For additional technical details, including a sequence diagram, see [Fleet's contributor documentation](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/MDM-end-user-authentication.md).
+For additional technical details, including a sequence diagram, see [Fleet's contributor documentation](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/product-groups/mdm/mdm-end-user-authentication.md).
 
 ## Summary
 

articles/escrowbudy-basics.md

@@ -25,7 +25,7 @@ When the disk encryption profile is delivered to a host, but a key is not yet es
 ## What’s going on behind the scenes?
 Behind the scenes, EscrowBuddy runs as a [macOS authorization plugin](https://developer.apple.com/documentation/security/authorization-plug-ins). It works in conjunction with the FileVault profile that Fleet deploys to hosts to enforce disk encryption.
 
-At the login event following deployment, EscrowBuddy generates a new recovery key, which is encrypted, wrapped in a CMS envelope, and saved at /var/db/FileVaultPRK.dat. Fleet collects this data from the host with the [vitals query](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Understanding-host-vitals.md#mdm_disk_encryption_key_file_darwin) that uses the [filevault_prk](https://fleetdm.com/tables/filevault_prk#apple) table to collect and escrow the key the next time the host is scheduled to refetch host details. 
+At the login event following deployment, EscrowBuddy generates a new recovery key, which is encrypted, wrapped in a CMS envelope, and saved at /var/db/FileVaultPRK.dat. Fleet collects this data from the host with the [vitals query](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/product-groups/orchestration/understanding-host-vitals.md#mdm_disk_encryption_key_file_darwin) that uses the [filevault_prk](https://fleetdm.com/tables/filevault_prk#apple) table to collect and escrow the key the next time the host is scheduled to refetch host details. 
 
 How can I learn more about EscrowBuddy’s technical details?
 Like Fleet, EscrowBuddy is an open source project, so the full source code can be inspected to learn more about what’s going on behind the scenes. Take a look at the [EscrowBuddy repo on GitHub](https://github.com/macadmins/escrow-buddy) to learn more.

articles/fleetctl.md

@@ -77,7 +77,7 @@ OPTIONS:
 
 ## Authentication
 
-This section walks you through authentication, assuming you already have a running Fleet instance. To learn how to set up new Fleet instance, check out the [Deploy](https://fleetdm.com/docs/deploy/introduction) section or [Building Fleet locally](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Building-Fleet.md) docs. 
+This section walks you through authentication, assuming you already have a running Fleet instance. To learn how to set up new Fleet instance, check out the [Deploy](https://fleetdm.com/docs/deploy/introduction) section or [Building Fleet locally](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/getting-started/building-fleet.md) docs. 
 
 ### Login
 

articles/get-current-telemetry-from-your-devices-with-live-queries.md

@@ -80,7 +80,7 @@ Documentation:
 
 * [Run live query with the UI](https://fleetdm.com/guides/queries)
 * [Run live query with REST API](https://fleetdm.com/docs/rest-api/rest-api#run-live-query)
-* [Run live query with WebSockets](https://github.com/fleetdm/fleet/blob/6fd06d648601edd89c01e25426e2e35ff2a8a37b/docs/Contributing/API-for-contributors.md#run-live-query)
+* [Run live query with WebSockets](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/reference/api-for-contributors.md#run-live-query)
 
 
 <meta name="articleTitle" value="Get current telemetry from your devices with live queries">

articles/standard-query-library.md

@@ -36,7 +36,7 @@ Do you want to add your own query?
 3. If you want to contribute multiple queries, please open one pull request that includes all your queries.
 
 For instructions on submitting pull requests to Fleet, check out [the Committing Changes
-section](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Committing-Changes.md#committing-changes) in the Contributors
+section](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/guides/committing-changes.md#committing-changes) in the Contributors
 documentation.
 
 

articles/vulnerability-processing.md

@@ -4,7 +4,7 @@ Vulnerability processing in Fleet detects vulnerabilities (CVEs) for the softwar
 
 To see what software is covered, check out the [Coverage section](#coverage).
 
-[Learn more](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Vulnerability-processing.md) about how it works for different platforms.
+[Learn more](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/guides/vulnerability-processing.md) about how it works for different platforms.
 
 <div purpose="embedded-content">
    <iframe src="https://www.youtube.com/embed/amJFecMWyvI" allowfullscreen></iframe>

articles/what-api-endpoints-to-expose-to-the-public-internet.md

@@ -33,7 +33,7 @@ If you would like to use Fleet's macOS MDM features, the following endpoints nee
 - `/mdm/apple/mdm`: Allows hosts to reach the server using the MDM protocol.
 - `/api/mdm/apple/enroll`: If you use automatic enrollment, allows hosts to get an enrollment profile.
 - `/api/*/fleet/device/*`: Provides end users access to their **My device** page.
-  - This page is where they download their manual enrollment profile, rotate their disk encryption key, and use other features. For more information on these API endpoints see the documentation [here](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/API-for-contributors.md#device-authenticated-routes).
+  - This page is where they download their manual enrollment profile, rotate their disk encryption key, and use other features. For more information on these API endpoints see the documentation [here](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/reference/api-for-contributors.md#device-authenticated-routes).
 - `/api/*/fleet/mdm/sso` and `/api/*/fleet/mdm/sso/callback`: If you use automatic enrollment and you require [end user authentication](https://fleetdm.com/docs/using-fleet/mdm-macos-setup-experience#end-user-authentication-and-eula) during out-of-the-box macOS setup, allows end users to authenticate with your IdP.
 - `/api/*/fleet/mdm/setup/eula/*`: If you use automatic enrollment and you require that the end user agrees to an [End User License Agreement (EULA)](https://fleetdm.com/docs/using-fleet/mdm-macos-setup-experience#end-user-authentication-and-eula) during out-of-the-box macOS setup, allows end user to see the EULA.
 - `/api/*/fleet/mdm/bootstrap`: If you use automatic enrollment and you install a [bootstrap package](https://fleetdm.com/docs/using-fleet/mdm-macos-setup-experience#bootstrap-package) during out-of-the-box macOS setup, installs the bootstrap package.

cmd/osquery-perf/README.md

@@ -72,7 +72,7 @@ In the Policy SQL:
 
 ## Running Locally (Development Environment)
 
-First, ensure your Fleet local development environment is up and running. Refer to [Building Fleet](../../docs/Contributing/Building-Fleet.md) for details. Once this is done:
+First, ensure your Fleet local development environment is up and running. Refer to [Building Fleet](../../docs/Contributing/getting-started/building-fleet.md) for details. Once this is done:
 
 * navigate to the Hosts tab of your Fleet web interface (typically, this would be at https://localhost:8080/hosts/manage).
 * click on "Manage enroll secret" and copy the enroll secret.

docs/Configuration/fleet-server-configuration.md

@@ -2705,7 +2705,7 @@ Minio users must set this to any non-empty value (e.g., `minio`), as Minio does
 
 > The [`server_private_key` configuration option](#server_private_key) is required for macOS MDM features.
 
-> The Apple Push Notification service (APNs), Simple Certificate Enrollment Protocol (SCEP), and Apple Business Manager (ABM) [certificate and key configuration](https://github.com/fleetdm/fleet/blob/fleet-v4.51.0/docs/Contributing/Configuration-for-contributors.md#mobile-device-management-mdm) are deprecated as of Fleet 4.51. They are maintained for backwards compatibility. Please upload your APNs certificate and ABM token. Learn how [here](https://fleetdm.com/docs/using-fleet/mdm-setup).
+> The Apple Push Notification service (APNs), Simple Certificate Enrollment Protocol (SCEP), and Apple Business Manager (ABM) [certificate and key configuration](https://github.com/fleetdm/fleet/blob/fleet-v4.51.0/docs/Contributing/reference/configuration-for-contributors.md#mobile-device-management-mdm) are deprecated as of Fleet 4.51. They are maintained for backwards compatibility. Please upload your APNs certificate and ABM token. Learn how [here](https://fleetdm.com/docs/using-fleet/mdm-setup).
 
 ### mdm.apple_scep_signer_validity_days
 

docs/Contributing/README.md

@@ -1,34 +1,35 @@
-# Contributing
+# Fleet Contributor Documentation
 
-### [Building Fleet](./Building-Fleet.md) 
-Learn about building the code, development infrastructure, and database migrations.
+Welcome to the Fleet contributor documentation! This documentation is designed to help you contribute to the Fleet project.
 
-### [Build and run Fleetd from local code](./Run-Locally-Built-Fleetd.md)
-Building and running your modified code.
+## Documentation Structure
 
-### [Testing](./Testing-and-local-development.md) 
-Look at Fleet's full test suite and integration tests.
+The documentation is organized into the following sections:
 
-### [Migrations](./Migrations.md)
-Learn about creating and updating database migrations.
+- [Getting Started](getting-started/README.md) - Setup, building, and testing Fleet
+- [Guides](guides/README.md) - How-to guides for common tasks
+- [Architecture](architecture/README.md) - High-level architecture documentation
+- [Product Groups](product-groups/README.md) - Documentation for specific product groups
+- [Workflows](workflows/README.md) - Development workflows
+- [Reference](reference/README.md) - API reference, configuration, etc.
+- [ADRs](adr/README.md) - Architectural Decision Records
+- [Research](research/) - Research documents for product groups
+- [Responsibilities](responsibilities/) - Responsibility documents for product groups
 
-### [Committing changes](./Committing-Changes.md) 
-Learn how to merge changes into the codebase.
+## Product Groups
 
-### [Releasing Fleet](./Releasing-Fleet.md) 
-Learn the process for how to release Fleet.
+Fleet is organized into three main product groups:
 
-### [Seeding data](./Seeding-Data.md) 
-Learn how to add fake data to your development instance.
+- [MDM](product-groups/mdm/README.md) - Mobile Device Management
+- [Orchestration](product-groups/orchestration/README.md) - Device orchestration using osquery
+- [Software](product-groups/software/README.md) - Software inventory, vulnerability management, and software installation
 
-### [API for contributors](./API-for-contributors.md) 
-Get to grips with Fleet API routes. This documentation is helpful for developing or contributing to Fleet.
+## Contributing
 
-### [Deploying ChromeOS test extensions](./Deploying-chrome-test-ext.md) 
-Learn how to deploy a test version of the fleetd Chrome extension for debug purposes.
+If you're new to Fleet, we recommend starting with the [Getting Started](getting-started/README.md) section to set up your development environment.
 
-### [Upgrading the Go version](./Upgrading-go-version.md) 
-Learn how to update the version of Go used to build Fleet.
+Once you're set up, you can explore the [Guides](guides/README.md) section to learn how to contribute to specific areas of the project.
 
-### [FAQ](./FAQ.md) 
-Find commonly asked questions and answers about contributing to Fleet as part of our community.
+## Architectural Decision Records (ADRs)
+
+We use [Architectural Decision Records](adr/README.md) to document significant architectural decisions. If you're making a significant architectural change, please create an ADR to document your decision.

docs/Contributing/adr/README.md

@@ -0,0 +1,40 @@
+# Architectural Decision Records (ADRs)
+
+This directory contains Architectural Decision Records (ADRs) for Fleet.
+
+## What are ADRs?
+
+Architectural Decision Records (ADRs) are documents that capture important architectural decisions made along with their context and consequences. They provide a record of architectural decisions that affect the system, the context in which they were made, and the rationale behind them.
+
+## Why use ADRs?
+
+ADRs help teams:
+- Document important decisions for future reference
+- Communicate the reasoning behind decisions
+- Onboard new team members by providing context
+- Track the evolution of the system architecture over time
+
+## ADR Format
+
+Each ADR follows a standard format:
+
+1. **Title**: A descriptive title that summarizes the decision
+2. **Status**: Proposed, Accepted, Rejected, Deprecated, or Superseded
+3. **Context**: The context and problem statement that led to this decision
+4. **Decision**: The decision that was made
+5. **Consequences**: The consequences of the decision, both positive and negative
+6. **References**: Any references to related documents or resources
+
+## Creating a New ADR
+
+To create a new ADR:
+
+1. Copy the [template](template.md) to a new file named `NNNN-descriptive-title.md` where `NNNN` is the next number in sequence
+2. Fill in the template with your decision
+3. Submit a pull request with your new ADR
+
+## ADR Index
+
+<!-- Add new ADRs to this list -->
+
+- [ADR Template](template.md)

docs/Contributing/adr/template.md

@@ -0,0 +1,49 @@
+# ADR-NNNN: Title
+
+## Status
+
+Proposed | Accepted | Rejected | Deprecated | Superseded
+
+If superseded, include a link to the new ADR:
+[ADR-NNNN: New ADR Title](NNNN-new-adr-title.md)
+
+## Date
+
+YYYY-MM-DD
+
+## Context
+
+Describe the context and problem statement. What is the issue that we're seeing that is motivating this decision or change?
+
+Include any constraints that influenced the decision (technical, business, or otherwise).
+
+## Decision
+
+Describe the decision that was made. State the decision in full sentences, with active voice.
+
+Explain the solution chosen and why it was selected over alternatives.
+
+## Consequences
+
+Describe the consequences of the decision, both positive and negative. This should include:
+
+- Benefits of implementing this decision
+- Drawbacks or technical debt incurred
+- Impact on existing systems or processes
+- Future considerations or follow-up decisions needed
+
+## Alternatives Considered
+
+Describe alternative solutions that were considered and why they were not chosen.
+
+For each alternative:
+- Describe the alternative approach
+- List pros and cons
+- Explain why it was not selected
+
+## References
+
+List any references, such as:
+- Links to related issues or discussions
+- External articles or documentation
+- Research or data that influenced the decision

docs/Contributing/architecture/README.md

@@ -0,0 +1,20 @@
+# Fleet Architecture Documentation
+
+This directory contains high-level architecture documentation for Fleet.
+
+## Overview
+
+- [High-Level Architecture](high-level-architecture.md) - Overview of Fleet's architecture
+- [Infrastructure](infrastructure.md) - Documentation on Fleet's infrastructure
+
+## Product Group Architecture
+
+Each product group has its own architecture documentation:
+
+- [MDM Architecture](mdm/README.md) - Architecture documentation for MDM
+- [Orchestration Architecture](orchestration/README.md) - Architecture documentation for Orchestration
+- [Software Architecture](software/README.md) - Architecture documentation for Software
+
+## Architectural Decision Records
+
+For significant architectural decisions, we use [Architectural Decision Records (ADRs)](../adr/README.md) to document the context, decision, and consequences.

docs/Contributing/architecture/high-level-architecture.md

@@ -5,7 +5,32 @@
 
 ## Overview
 
-Add text
+Fleet's architecture follows a client-server model designed for scalability, security, and flexibility. The system consists of several key components that work together to provide device management, orchestration, and software management capabilities.
+
+At a high level, Fleet consists of:
+
+1. **Fleet Server**: The central component that handles API requests, manages the database, processes queries, and coordinates communication between all parts of the system. It provides both REST and GraphQL APIs for clients to interact with.
+
+2. **Agent (fleetd)**: A lightweight agent installed on managed devices that includes:
+   - **orbit**: The core agent component that manages communication with the Fleet server
+   - **osqueryd**: The osquery daemon that executes queries and returns results
+   - **Fleet Desktop**: An optional component that provides a local UI for end users
+
+3. **Clients**: Various ways to interact with Fleet:
+   - **Web UI**: A React-based frontend for administrators
+   - **fleetctl CLI**: Command-line interface for automation and scripting
+   - **Raw API**: Direct API access for custom integrations
+
+4. **Storage**:
+   - **MySQL**: Primary database for storing configuration, device information, and query results
+   - **Redis**: Used for caching and managing live query results
+
+5. **External Services**:
+   - **TUF Server**: Provides secure updates for the agent components
+   - **Telemetry**: Optional monitoring via Prometheus, OpenTelemetry, or Elastic APM
+   - **External Logging**: Optional integration with external logging systems
+
+The diagrams below illustrate how these components interact and the data flow for different operations like live queries, scheduled queries, and vulnerability management.
 
 ## Main System Components
 

docs/Contributing/architecture/infrastructure.md

@@ -12,10 +12,5 @@ The following are quick links to infrastructure-related README files in both pub
 ### Best practices for containers
 Follow the industry best practices when designing and deploying infrastructure. For containerized infrastructure, Google has created a [reference document](https://cloud.google.com/architecture/best-practices-for-operating-containers) as an ideal reference for these practices.
 
-
-
-
-
-
 <meta name="pageOrderInSection" value="1700">
-<meta name="description" value="Infrastructure info.">
+<meta name="description" value="Infrastructure info.">

docs/Contributing/architecture/mdm/README.md

@@ -0,0 +1,21 @@
+# MDM Architecture
+
+This directory contains documentation about Fleet's Mobile Device Management (MDM) architecture.
+
+## Overview
+
+Fleet's MDM architecture is designed to manage devices across different platforms, including Apple (macOS, iOS, iPadOS), Windows, and Android. This documentation provides insights into the design decisions, system components, and interactions specific to the MDM functionality.
+
+## Contents
+
+- [MDM Overview](mdm-overview.md) - Overview of Fleet's MDM architecture
+- [Apple MDM Architecture](apple-mdm-architecture.md) - Architecture specific to Apple MDM
+- [Windows MDM Architecture](windows-mdm-architecture.md) - Architecture specific to Windows MDM
+- [End User Authentication](end-user-authentication.md) - Architecture for end user authentication
+- [Disk Encryption](disk-encryption.md) - Architecture for disk encryption
+- [Automated Device Enrollment](automated-device-enrollment.md) - Architecture for automated device enrollment
+
+## Related Resources
+
+- [MDM Product Group Documentation](../../product-groups/mdm/) - Documentation for the MDM product group
+- [MDM Development Guides](../../guides/mdm/) - Guides for MDM development

docs/Contributing/architecture/mdm/apple-mdm-architecture.md

@@ -0,0 +1,8 @@
+# Apple MDM Architecture
+
+This document provides an overview of Fleet's Apple Mobile Device Management (MDM) architecture.
+
+## Introduction
+
+Fleet's Apple MDM architecture is designed to manage Apple devices, including macOS and iOS devices. This document provides insights into the design decisions, system components, and interactions specific to the Apple MDM functionality.
+

docs/Contributing/architecture/mdm/automated-device-enrollment.md

@@ -0,0 +1,57 @@
+# Automated Device Enrollment Architecture
+
+This document provides an overview of Fleet's Automated Device Enrollment (ADE) architecture for MDM.
+
+## Introduction
+
+Automated Device Enrollment (ADE) in Fleet's MDM allows for zero-touch deployment of devices, enabling organizations to automatically enroll and configure devices without manual intervention. This document provides insights into the design decisions, system components, and interactions specific to the ADE functionality.
+
+## Architecture Overview
+
+The ADE architecture integrates with platform-specific enrollment programs (Apple Business Manager/Apple School Manager for Apple devices) to automatically enroll devices when they are activated.
+
+## Key Components
+
+- **Enrollment Program Integration**: Integration with platform-specific enrollment programs.
+- **Device Assignment**: Mapping between devices and enrollment configurations.
+- **Enrollment Profiles**: Configurations applied during the enrollment process.
+- **Synchronization**: Mechanisms to synchronize device information with enrollment programs.
+
+## Architecture Diagram
+
+```
+[Placeholder for Automated Device Enrollment Architecture Diagram]
+```
+
+## Platform-Specific Implementation
+
+### Apple Automated Device Enrollment
+
+For Apple devices, ADE (formerly known as DEP) involves the following components:
+
+- **Apple Business Manager/Apple School Manager**: Web portals for managing device enrollment.
+- **MDM Server Tokens**: Tokens that authenticate the MDM server with Apple's services.
+- **Enrollment Profiles**: Configurations that define the enrollment experience.
+- **Device Assignments**: Mapping between devices and enrollment profiles.
+
+#### Synchronization Process
+
+Synchronization of devices from all ABM tokens uploaded to Fleet happens in the `dep_syncer` cron job, which runs every 1 minute.
+
+We keep a record of all devices ingested via the ADE sync in the `host_dep_assignments` table. Entries in this table are soft-deleted.
+
+On every run, we pull the list of added/modified/deleted devices and:
+
+1. If the host was added/modified, we:
+   - Create/match a row in the `hosts` table for the new host. This allows IT admin to view the host by serial in team lists before it turns on MDM or has `fleetd` installed.
+   - Always assign a JSON profile for added devices. We assign JSON profile for modified devices if the profile has not been modified according to Apple DEP device response.
+2. If the host was deleted, we soft delete the `host_dep_assignments` entry.
+
+#### Special Case: Host in ABM is Deleted in Fleet
+
+If an IT admin deletes a host in the UI/API, and we have a non-deleted entry in `host_dep_assignments` for the host, we immediately create a new host entry as if the device was just ingested from the ABM sync.
+
+## Related Resources
+
+- [MDM Product Group Documentation](../../product-groups/mdm/) - Documentation for the MDM product group
+- [MDM Development Guides](../../guides/mdm/) - Guides for MDM development

docs/Contributing/architecture/mdm/disk-encryption.md

@@ -0,0 +1,61 @@
+# Disk Encryption Architecture
+
+This document provides an overview of Fleet's Disk Encryption architecture for MDM.
+
+## Introduction
+
+Disk Encryption in Fleet's MDM allows for securing device data by encrypting the storage media. This document provides insights into the design decisions, system components, and interactions specific to the Disk Encryption functionality.
+
+## Architecture Overview
+
+The Disk Encryption architecture leverages platform-specific encryption technologies (FileVault for macOS, BitLocker for Windows, LUKS via LVM for Linux) to encrypt device storage and securely manage recovery keys.
+
+## Key Components
+
+- **Encryption Configuration**: Settings and policies for configuring disk encryption.
+- **Key Management**: Secure storage and retrieval of encryption keys.
+- **Verification**: Mechanisms to verify the encryption status of devices.
+- **Recovery**: Processes for recovering access to encrypted devices.
+
+## Architecture Diagram
+
+```
+[Placeholder for Disk Encryption Architecture Diagram]
+```
+
+## Platform-Specific Implementation
+
+### FileVault (macOS)
+
+For macOS, disk encryption involves a two-step process:
+
+1. Sending a profile with two payloads:
+   - A Payload to configure how the disk is going to be encrypted
+   - A Payload to configure the escrow of the encryption key
+
+2. Retrieving the disk encryption key:
+   - Via osquery, we grab the (encrypted) disk encryption key
+   - In a cron job, we verify that we're able to decrypt the key
+
+If we're not able to decrypt the key for a host, the key needs to be rotated. Rotation happens silently by:
+
+1. The server sends a notification to orbit, notifying that the key couldn't be decrypted.
+2. orbit enables an authorization plugin named [Escrow Buddy](https://github.com/macadmins/escrow-buddy) that performs the key rotation the next time the user logs in.
+3. Fleet retrieves and tries to validate the key again.
+
+### BitLocker (Windows)
+
+Disk encryption in Windows is performed entirely by orbit.
+
+When disk encryption is enabled, the server sends a notification to orbit, who calls the [Win32_EncryptableVolume class](https://learn.microsoft.com/en-us/windows/win32/secprov/getencryptionmethod-win32-encryptablevolume) to encrypt/decrypt the disk and generate an encryption key.
+
+After the disk is encrypted, orbit sends the key back to the server using an orbit-authenticated endpoint (`POST /api/fleet/orbit/disk_encryption_key`).
+
+## Key Storage and Security
+
+Encryption keys are stored in the `host_disk_encryption_keys` table. The value for the key is encrypted using Fleet's CA certificate, and thus can only be decrypted if you have the CA private key.
+
+## Related Resources
+
+- [MDM Product Group Documentation](../../product-groups/mdm/) - Documentation for the MDM product group
+- [MDM Development Guides](../../guides/mdm/) - Guides for MDM development

docs/Contributing/architecture/mdm/end-user-authentication.md

@@ -0,0 +1,52 @@
+# End User Authentication Architecture
+
+This document provides an overview of Fleet's End User Authentication architecture for MDM.
+
+## Introduction
+
+End User Authentication in Fleet's MDM allows for associating managed devices with specific users, enabling user-based policies and personalized device management. This document provides insights into the design decisions, system components, and interactions specific to the End User Authentication functionality.
+
+## Architecture Overview
+
+The End User Authentication architecture integrates with identity providers (IdPs) to authenticate users and associate them with their devices. This enables user-specific policies and configurations to be applied to devices.
+
+## Key Components
+
+- **Identity Provider Integration**: Integration with external identity providers such as Okta, Azure AD, and Google Workspace.
+- **User-Device Association**: Mapping between users and their devices.
+- **Authentication Flow**: The process by which users authenticate and are associated with their devices.
+
+## Architecture Diagram
+
+```
+[Placeholder for End User Authentication Architecture Diagram]
+```
+
+## Authentication Flows
+
+### Automated Authentication
+
+1. New device starts the enrollment process and is prompted to login to the IDP.
+2. Fleet captures the username and stores it to register after enrollment.
+3. Device enrolls with the MDM server.
+4. Optionally MDM server maps user information to SCIM data already sent by IdP.
+5. MDM server associates the user with the device.
+
+## Identity Provider Integration
+
+Fleet integrates with various identity providers to authenticate users:
+
+- **SAML**: For integration with SAML-based identity providers such as Okta and Azure AD.
+
+## User-Device Association
+
+User-device association is stored in the Fleet database and is used to apply user-specific policies and configurations to devices. The association can be established through:
+
+- **Directory Integration**: When user information is retrieved from a directory service.
+- **Automated Authentication**: When a user enrolls in MDM after authenticating with an IDP.
+
+## Related Resources
+
+- [MDM Product Group Documentation](../../product-groups/mdm/) - Documentation for the MDM product group
+- [MDM Development Guides](../../guides/mdm/) - Guides for MDM development
+- [MDM End User Authentication](../../product-groups/mdm/mdm-end-user-authentication.md) - Detailed documentation on MDM end user authentication

docs/Contributing/architecture/mdm/mdm-overview.md

@@ -0,0 +1,47 @@
+# MDM Architecture Overview
+
+This document provides an overview of Fleet's Mobile Device Management (MDM) architecture.
+
+## Introduction
+
+Fleet's MDM architecture is designed to manage devices across different platforms, including Apple (macOS, iOS) and Windows. This document provides insights into the design decisions, system components, and interactions specific to the MDM functionality.
+
+## System Components
+
+The MDM architecture consists of the following main components:
+
+- **MDM Server**: The central component that manages device enrollment, configuration, and commands.
+- **Device Enrollment**: The process by which devices are registered with the MDM server.
+- **Configuration Profiles**: Settings and policies that are applied to managed devices.
+- **Commands**: Instructions sent to devices to perform specific actions.
+- **Device Communication**: The protocols and mechanisms used for communication between the MDM server and devices.
+
+## Architecture Diagram
+
+```
+[Placeholder for MDM Architecture Diagram]
+```
+
+## Integration Points
+
+The MDM architecture integrates with the following components:
+
+- **Fleet Server**: For device management and policy enforcement.
+- **Database**: For storing device information, configurations, and policies.
+- **Authentication Systems**: For user and device authentication.
+- **Certificate Authorities**: For issuing and managing device certificates.
+
+## Platform-Specific Considerations
+
+### Apple MDM
+
+See [Apple MDM Architecture](apple-mdm-architecture.md) for details on Apple-specific MDM architecture.
+
+### Windows MDM
+
+See [Windows MDM Architecture](windows-mdm-architecture.md) for details on Windows-specific MDM architecture.
+
+## Related Resources
+
+- [MDM Product Group Documentation](../../product-groups/mdm/) - Documentation for the MDM product group
+- [MDM Development Guides](../../guides/mdm/) - Guides for MDM development

docs/Contributing/architecture/mdm/windows-mdm-architecture.md

@@ -0,0 +1,62 @@
+# Windows MDM Architecture
+
+This document provides an overview of Fleet's Windows Mobile Device Management (MDM) architecture.
+
+## Introduction
+
+Fleet's Windows MDM architecture is designed to manage Windows devices. This document provides insights into the design decisions, system components, and interactions specific to the Windows MDM functionality.
+
+## Windows MDM Protocol
+
+Windows MDM is based on the OMA Device Management (OMA-DM) protocol and uses SyncML for data exchange. Microsoft has extended the protocol with Windows-specific features and capabilities.
+
+### Key Components
+
+- **MDM Enrollment**: The process by which devices are registered with the MDM server.
+- **MDM Sync**: The process by which devices communicate with the MDM server.
+- **Configuration Service Providers (CSPs)**: Components that provide an interface to device settings.
+- **MDM Policies**: Settings and configurations applied to managed devices.
+
+## Architecture Diagram
+
+```
+[Placeholder for Windows MDM Architecture Diagram]
+```
+
+## Enrollment Flows
+
+### User-Initiated Enrollment
+
+1. User downloads and installs the enrollment package.
+2. Device enrolls with the MDM server.
+3. MDM server sends initial configuration profiles.
+
+### Azure AD Join
+
+1. Device is joined to Azure AD.
+2. Device automatically enrolls with the MDM server.
+
+## Configuration Service Providers (CSPs)
+
+Windows MDM uses Configuration Service Providers (CSPs) to configure and manage devices. CSPs are the interface through which the MDM server can access and modify device settings.
+
+Common CSPs used by Fleet include:
+
+- **Policy CSP**: For configuring device policies.
+- **EnterpriseModernAppManagement CSP**: For managing modern applications.
+- **DeviceStatus CSP**: For retrieving device status information.
+- **WindowsUpdatePolicy CSP**: For configuring Windows Update settings.
+
+## SyncML Structure
+
+Windows MDM uses SyncML for communication between the device and the MDM server. A typical SyncML message includes:
+
+- **Header**: Contains session information.
+- **Body**: Contains commands and data.
+- **Status**: Contains the result of previous commands.
+
+## Related Resources
+
+- [MDM Product Group Documentation](../../product-groups/mdm/) - Documentation for the MDM product group
+- [MDM Development Guides](../../guides/mdm/) - Guides for MDM development
+- [Windows MDM Glossary and Protocol](../../product-groups/mdm/windows-mdm-glossary-and-protocol.md) - Glossary of Windows MDM terms and protocol details

docs/Contributing/architecture/orchestration/README.md

@@ -0,0 +1,21 @@
+# Orchestration Architecture
+
+This directory contains documentation about Fleet's Orchestration architecture.
+
+## Overview
+
+Fleet's Orchestration architecture is designed to manage and query devices at scale using osquery, providing visibility into device status, configuration, and security posture. This documentation provides insights into the design decisions, system components, and interactions specific to the Orchestration functionality.
+
+## Contents
+
+- [Orchestration Overview](orchestration-overview.md) - Overview of Fleet's Orchestration architecture
+- [Live Queries](live-queries.md) - Architecture for live queries
+- [Scheduled Queries](scheduled-queries.md) - Architecture for scheduled queries
+- [Query Packs](query-packs.md) - Architecture for query packs
+- [Host Vitals](host-vitals.md) - Architecture for host vitals
+- [Teams and Access Control](teams-and-access-control.md) - Architecture for teams and access control
+
+## Related Resources
+
+- [Orchestration Product Group Documentation](../../product-groups/orchestration/) - Documentation for the Orchestration product group
+- [Orchestration Development Guides](../../guides/orchestration/) - Guides for Orchestration development

docs/Contributing/architecture/orchestration/host-vitals.md

@@ -0,0 +1,74 @@
+# Host Vitals Architecture
+
+This document provides an overview of Fleet's Host Vitals architecture.
+
+## Introduction
+
+Host Vitals in Fleet provide real-time and historical information about the health and status of devices, including CPU usage, memory usage, disk usage, and uptime. This document provides insights into the design decisions, system components, and interactions specific to the Host Vitals functionality.
+
+## Architecture Overview
+
+The Host Vitals architecture enables the collection, processing, and visualization of device health metrics across a fleet of devices. It leverages osquery's capabilities to collect system metrics and Fleet's infrastructure to process and display them.
+
+## Key Components
+
+- **Metrics Collection**: The process of collecting system metrics from devices.
+- **Metrics Processing**: The processing of collected metrics for storage and analysis.
+- **Metrics Storage**: The storage of metrics for historical analysis.
+- **Metrics Visualization**: The display of metrics in the Fleet UI.
+
+## Architecture Diagram
+
+```
+[Placeholder for Host Vitals Architecture Diagram]
+```
+
+## Metrics Collection Flow
+
+### 1 - Agent Collects Metrics
+
+```
+osquery agent -> Server
+```
+
+1. osquery agent collects system metrics using osquery tables.
+2. osquery agent sends the metrics to the Fleet server.
+
+### 2 - Server Processes and Stores Metrics
+
+```
+Server -> DB
+```
+
+1. Server processes the received metrics.
+2. Server stores the metrics in the database.
+
+### 3 - UI Displays Metrics
+
+```
+UI -> Server -> DB
+```
+
+1. UI requests metrics from the server.
+2. Server retrieves metrics from the database.
+3. Server returns metrics to the UI.
+4. UI displays the metrics.
+
+## Host vitals collected
+
+See the [host details API](https://fleetdm.com/docs/rest-api/rest-api#get-host) documentation for details on collected vitals.
+
+## Performance Considerations
+
+Host Vitals collection can impact device and server performance, especially for large fleets. The following considerations should be taken into account:
+
+- **Collection Frequency**: More frequent collection can impact device performance.
+- **Metric Count**: Collecting more metrics can impact device and server performance.
+- **Fleet Size**: Collecting metrics from a large number of devices can impact server performance.
+
+## Related Resources
+
+- [Host details API documentation](https://fleetdm.com/docs/rest-api/rest-api#get-host)
+- [Orchestration Product Group Documentation](../../product-groups/orchestration/) - Documentation for the Orchestration product group
+- [Orchestration Development Guides](../../guides/orchestration/) - Guides for Orchestration development
+- [Understanding Host Vitals](../../product-groups/orchestration/understanding-host-vitals.md) - Detailed documentation on host vitals

docs/Contributing/architecture/orchestration/live-queries.md

@@ -0,0 +1,8 @@
+# Live queries
+
+Live queries in Fleet allow users to execute ad-hoc queries against devices in real-time, providing immediate visibility into device status, configuration, and security posture. This document provides insights into the design decisions, system components, and interactions specific to the Live Queries functionality.
+
+See our [live queries guide](https://fleetdm.com/guides/get-current-telemetry-from-your-devices-with-live-queries) to learn more about the architecture, implementation, and use of live queries.
+
+## Related resources
+- [Live queries guide](https://fleetdm.com/guides/get-current-telemetry-from-your-devices-with-live-queries)

docs/Contributing/architecture/orchestration/orchestration-overview.md

@@ -0,0 +1,65 @@
+# Orchestration Architecture Overview
+
+This document provides an overview of Fleet's Orchestration architecture.
+
+## Introduction
+
+Fleet's Orchestration architecture is designed to manage and query devices at scale using osquery, providing visibility into device status, configuration, and security posture. This document provides insights into the design decisions, system components, and interactions specific to the Orchestration functionality.
+
+## System Components
+
+The Orchestration architecture consists of the following main components:
+
+- **Fleet Server**: The central component that manages device communication, query execution, and result processing.
+- **osquery**: The open-source agent that runs on devices and executes queries.
+- **Query Engine**: The component that processes and executes queries on devices.
+- **Result Processing**: The component that processes and stores query results.
+- **Teams and Access Control**: The component that manages user access to devices and queries.
+
+## Architecture Diagram
+
+```
+[Placeholder for Orchestration Architecture Diagram]
+```
+
+## Query Types
+
+Fleet supports two main types of queries:
+
+- **Live Queries**: Ad-hoc queries that are executed in real-time and return results immediately.
+- **Scheduled Queries**: Queries that are executed on a schedule and store results for later analysis.
+
+### Live Queries
+
+Live queries are executed in real-time and return results immediately. The process for executing a live query is as follows:
+
+1. User initiates a query through the UI or API.
+2. Fleet server creates a campaign for the query.
+3. Devices check in with the Fleet server and receive the query.
+4. Devices execute the query and return results.
+5. Fleet server processes and displays the results.
+
+### Scheduled Queries
+
+Scheduled queries are executed on a schedule and store results for later analysis. The process for executing a scheduled query is as follows:
+
+1. User creates a scheduled query through the UI or API.
+2. Fleet server stores the query in the database.
+3. Devices check in with the Fleet server and receive the query configuration.
+4. Devices execute the query on the specified schedule.
+5. Devices return results to the Fleet server.
+6. Fleet server processes and stores the results.
+
+## Integration Points
+
+The Orchestration architecture integrates with the following components:
+
+- **Fleet Server**: For device management and query execution.
+- **Database**: For storing query configurations and results.
+- **Redis**: For storing live query results.
+- **External Logging Systems**: For storing query results for long-term analysis.
+
+## Related Resources
+
+- [Orchestration Product Group Documentation](../../product-groups/orchestration/) - Documentation for the Orchestration product group
+- [Orchestration Development Guides](../../guides/orchestration/) - Guides for Orchestration development

docs/Contributing/architecture/orchestration/query-packs.md

@@ -0,0 +1,78 @@
+# Query Packs Architecture
+
+This document provides an overview of Fleet's Query Packs architecture.
+
+## Introduction
+
+Query packs in Fleet allow users to group related queries together for easier management and distribution. This document provides insights into the design decisions, system components, and interactions specific to the Query Packs functionality.
+
+## Architecture Overview
+
+The Query Packs architecture enables the organization, configuration, and distribution of groups of queries across a fleet of devices. It leverages osquery's pack capabilities to execute multiple queries on devices and return results to the Fleet server.
+
+## Key Components
+
+- **Pack Definition**: The definition of a pack, including the queries it contains and their schedules.
+- **Pack Distribution**: The mechanism for distributing packs to devices.
+- **Query Execution**: The process of executing queries within a pack.
+- **Result Collection**: The process of collecting and processing query results.
+
+## Architecture Diagram
+
+```
+[Placeholder for Query Packs Architecture Diagram]
+```
+
+## Pack Execution Flow
+
+### 1 - Fleet User Creates a Query Pack
+
+```
+Fleet User -> API Client (Frontend or Fleetctl) -> Server -> DB
+```
+
+1. Fleet user creates a query pack for a team or globally through the UI or API.
+2. Server stores the pack configuration in the database.
+
+### 2 - Agent Gets Config File (with the Query Pack)
+
+```
+osquery agent -> Server -> DB
+```
+
+1. osquery agent requests the configuration file from the server.
+2. Server merges team and global configurations, including packs.
+3. Server returns the merged configuration to the agent.
+
+### 3 - Agent Executes Queries and Returns Results
+
+```
+osquery agent -> Server -> Optional External Log
+```
+
+1. osquery agent runs the queries in the pack according to their schedules.
+2. osquery agent sends the results to the server.
+3. Server optionally forwards the results to an external logging system.
+
+## Pack Configuration
+
+Query packs have several configuration options:
+
+- **Name**: The name of the pack.
+- **Description**: A description of the pack's purpose.
+- **Queries**: The queries included in the pack.
+- **Targets**: The devices or teams targeted by the pack.
+- **Schedules**: The schedules for each query in the pack.
+
+## Performance Considerations
+
+Query packs can impact device performance, especially for packs with complex queries or queries that run frequently. The following considerations should be taken into account:
+
+- **Query Complexity**: Complex queries can consume significant CPU resources on devices.
+- **Query Frequency**: Queries that run frequently can impact device performance.
+- **Pack Size**: Packs with many queries can impact device performance.
+
+## Related Resources
+
+- [Orchestration Product Group Documentation](../../product-groups/orchestration/) - Documentation for the Orchestration product group
+- [Orchestration Development Guides](../../guides/orchestration/) - Guides for Orchestration development

docs/Contributing/architecture/orchestration/scheduled-queries.md

@@ -0,0 +1,75 @@
+# Scheduled Queries Architecture
+
+This document provides an overview of Fleet's Scheduled Queries architecture.
+
+## Introduction
+
+Scheduled queries in Fleet allow users to configure queries that run on a regular schedule, providing ongoing visibility into device status, configuration, and security posture. This document provides insights into the design decisions, system components, and interactions specific to the Scheduled Queries functionality.
+
+## Architecture Overview
+
+The Scheduled Queries architecture enables the configuration, distribution, and execution of queries on a schedule across a fleet of devices. It leverages osquery's scheduled query capabilities to execute SQL queries on devices and return results to the Fleet server.
+
+## Key Components
+
+- **Query Configuration**: The definition of a query, including the SQL statement, schedule, and target devices.
+- **Configuration Distribution**: The mechanism for distributing query configurations to devices.
+- **Result Collection**: The process of collecting and processing query results.
+- **Result Storage**: The storage of query results for analysis and alerting.
+
+## Architecture Diagram
+
+```
+[Placeholder for Scheduled Queries Architecture Diagram]
+```
+
+## Query Execution Flow
+
+### 1 - Fleet User Creates a Scheduled Query
+
+```
+Fleet User -> API Client (Frontend or Fleetctl) -> Server -> DB
+```
+
+1. Fleet user creates a scheduled query for a team or globally through the UI or API.
+2. Server stores the query configuration in the database.
+
+### 2 - Agent Gets Config File (with the Scheduled Query)
+
+```
+osquery agent -> Server -> DB
+```
+
+1. osquery agent requests the configuration file from the server.
+2. Server merges team and global configurations.
+3. Server returns the merged configuration to the agent.
+
+### 3 - Agent Returns Results to be (Optionally) Logged
+
+```
+osquery agent -> Server -> Optional External Log
+```
+
+1. osquery agent runs the query according to the schedule.
+2. osquery agent sends the results to the server.
+3. Server optionally forwards the results to an external logging system.
+
+## Configuration Options
+
+osquery agents have several configuration options that affect scheduled queries:
+
+1. **Config TLS Refresh**: The frequency at which the agent pulls down the configuration file (typically 10 seconds).
+2. **Logger TLS**: The frequency of sending query results (typically 10 seconds).
+
+## Performance Considerations
+
+Scheduled queries can impact device performance, especially for complex queries or queries that run frequently. The following considerations should be taken into account:
+
+- **Query Complexity**: Complex queries can consume significant CPU resources on devices.
+- **Query Frequency**: Queries that run frequently can impact device performance.
+- **Result Size**: Large result sets can consume significant memory and network bandwidth.
+
+## Related Resources
+
+- [Orchestration Product Group Documentation](../../product-groups/orchestration/) - Documentation for the Orchestration product group
+- [Orchestration Development Guides](../../guides/orchestration/) - Guides for Orchestration development

docs/Contributing/architecture/orchestration/teams-and-access-control.md

@@ -0,0 +1,29 @@
+# Teams and Access Control Architecture
+
+This document provides an overview of Fleet's Teams and Access Control architecture.
+
+## Introduction
+
+Teams and Access Control in Fleet enable organizations to manage user access to devices, queries, and other resources based on team membership and roles. This document provides insights into the design decisions, system components, and interactions specific to the Teams and Access Control functionality.
+
+## Architecture Overview
+
+The Teams and Access Control architecture enables the organization of devices and users into teams, and the management of user access to resources based on team membership and roles.
+
+## Key Components
+
+- **Teams**: Logical groupings of devices and users.
+- **Roles**: Sets of permissions that define what actions users can perform.
+- **Access Control**: The mechanism for controlling user access to resources.
+- **Resource Ownership**: The association of resources with teams.
+
+## Role-Based Access Control
+
+Fleet uses role-based access control (RBAC) to manage user access to resources. Roles define what actions users can perform on resources. See our [RBAC guide](https://fleetdm.com/guides/role-based-access) for details.
+
+## Related Resources
+
+- [Role-based access control guide](https://fleetdm.com/guides/role-based-access)
+- [Orchestration Product Group Documentation](../../product-groups/orchestration/) - Documentation for the Orchestration product group
+- [Orchestration Development Guides](../../guides/orchestration/) - Guides for Orchestration development
+- [Teams](../../product-groups/orchestration/teams.md) - Detailed documentation on teams

docs/Contributing/architecture/software/README.md

@@ -0,0 +1,18 @@
+# Software architecture
+
+Fleet's software architecture is designed to manage software across the device fleet, including software inventory, vulnerability management, and software installation. This directory contains documentation about Fleet's software architecture.
+
+## Contents
+
+- [Software Overview](software-overview.md) - Overview of Fleet's software architecture
+- [Software Inventory](software-inventory.md) - Architecture for software inventory
+- [Vulnerability management](vulnerability-management.md) - Architecture for vulnerability management
+- [Vulnerability processing](vulnerability-processing.md) - Architecture for vulnerability processing
+- [Software Installation](software-installation.md) - Architecture for software installation
+- [Software Updates](software-updates.md) - Architecture for software updates
+- [Software automations](software-automations.md) - Architecture for software automations
+
+## Related resources
+
+- [Software Product Group Documentation](../../product-groups/software/) - Documentation for the Software product group
+- [Software Development Guides](../../guides/software/) - Guides for Software development

docs/Contributing/architecture/software/software-automations.md

@@ -0,0 +1,22 @@
+# Software Policies Architecture
+
+This document provides an overview of Fleet's software automation architecture.
+
+## Introduction
+
+Software automation in Fleet enable organizations automatically install or update software based on a policy.
+
+## Architecture Overview
+
+## Key Components
+
+## Architecture Diagram
+
+```
+[Placeholder for Software Policies Architecture Diagram]
+```
+
+## Related Resources
+
+- [Software Product Group Documentation](../../product-groups/software/) - Documentation for the Software product group
+- [Software Development Guides](../../guides/software/) - Guides for Software development

docs/Contributing/architecture/software/software-installation.md

@@ -0,0 +1,36 @@
+# Software installation architecture
+
+This document provides an overview of Fleet's software installation architecture.
+
+## Introduction
+
+Software installation in Fleet enables the deployment and installation of software packages across the device fleet. This document provides insights into the design decisions, system components, and interactions specific to the Software Installation functionality.
+
+## Architecture overview
+
+## Key components
+
+## Architecture diagram
+
+```
+[Placeholder for software installation architecture diagram]
+```
+
+## Installation flow
+
+## Platform-specific implementation
+
+### macOS
+
+### Windows
+
+### Linux
+
+### iOS/iPadOS 
+
+### Android
+
+## Related resources
+
+- [Software product group documentation](../../product-groups/software/) - Documentation for the Software product group
+- [Software development guides](../../guides/software/) - Guides for Software development

docs/Contributing/architecture/software/software-inventory.md

@@ -0,0 +1,13 @@
+# Software Inventory Architecture
+
+This document provides an overview of Fleet's Software Inventory architecture.
+
+## Introduction
+
+Software Inventory in Fleet provides visibility into the software installed on devices across the fleet. This document provides insights into the design decisions, system components, and interactions specific to the Software Inventory functionality.
+
+## Architecture overview
+
+## Key components
+
+## Architecture diagram

docs/Contributing/architecture/software/software-overview.md

@@ -0,0 +1,70 @@
+# Software Architecture Overview
+
+This document provides an overview of Fleet's Software architecture.
+
+## Introduction
+
+Fleet's Software architecture is designed to manage software across the device fleet, including software inventory, vulnerability management, and software installation. This document provides insights into the design decisions, system components, and interactions specific to the Software functionality.
+
+## System Components
+
+The Software architecture consists of the following main components:
+
+- **Software Inventory**: The component that collects and manages information about installed software.
+- **Vulnerability Management**: The component that identifies and manages software vulnerabilities.
+- **Software Installation**: The component that manages the installation of software on devices.
+- **Software Updates**: The component that manages software updates on devices.
+- **Software Policies**: The component that defines and enforces software policies.
+
+## Architecture Diagram
+
+```
+[Placeholder for Software Architecture Diagram]
+```
+
+## Software Inventory
+
+The Software Inventory component collects and manages information about installed software on devices. It leverages osquery's capabilities to collect software information and Fleet's infrastructure to process and display it.
+
+### Inventory Collection Flow
+
+1. osquery agent collects software information using osquery tables.
+2. osquery agent sends the information to the Fleet server.
+3. Server processes and stores the information in the database.
+4. UI displays the information to users.
+
+## Vulnerability Management
+
+The Vulnerability Management component identifies and manages software vulnerabilities in the device fleet. It compares installed software versions with known vulnerabilities and provides information about affected devices.
+
+### Vulnerability Identification Flow
+
+1. Server retrieves software inventory information from the database.
+2. Server compares software versions with vulnerability databases.
+3. Server identifies vulnerable software and affected devices.
+4. UI displays vulnerability information to users.
+
+## Software Installation
+
+The Software Installation component manages the installation of software on devices. It leverages platform-specific mechanisms to install software packages.
+
+### Installation Flow
+
+1. User initiates software installation through the UI or API.
+2. Server sends installation instructions to the device.
+3. Device installs the software using platform-specific mechanisms.
+4. Device reports installation status to the server.
+
+## Integration Points
+
+The Software architecture integrates with the following components:
+
+- **Fleet Server**: For device management and software inventory collection.
+- **Database**: For storing software inventory and vulnerability information.
+- **External Vulnerability Databases**: For retrieving vulnerability information.
+- **Platform-Specific Installation Mechanisms**: For installing software on devices.
+
+## Related Resources
+
+- [Software Product Group Documentation](../../product-groups/software/) - Documentation for the Software product group
+- [Software Development Guides](../../guides/software/) - Guides for Software development

docs/Contributing/architecture/software/software-updates.md

@@ -0,0 +1,38 @@
+# Software updates architecture
+
+This document provides an overview of Fleet's software updates architecture.
+
+## Introduction
+
+Software updates in Fleet enables the management and deployment of software updates across the device fleet. This document provides insights into the design decisions, system components, and interactions specific to the Software updates functionality.
+
+## Architecture overview
+
+The software updates architecture enables the identification, configuration, and deployment of software updates across a fleet of devices. It leverages platform-specific mechanisms to update software on devices.
+
+## Key components
+
+## Architecture diagram
+
+```
+[Placeholder for software updates architecture diagram]
+```
+
+## Update flow
+
+## Platform-specific implementation
+
+### macOS
+
+### Windows
+
+### Linux
+
+### iOS/iPadOS
+
+### Android
+
+## Related resources
+
+- [Software product group documentation](../../product-groups/software/) - Documentation for the software product group
+- [Software development guides](../../guides/software/) - Guides for software development

docs/Contributing/architecture/software/vulnerability-management.md

@@ -0,0 +1,39 @@
+# Vulnerability management architecture
+
+This document provides an overview of Fleet's vulnerability management architecture.
+
+## Introduction
+
+Vulnerability management in Fleet identifies and manages software vulnerabilities in the device fleet. This document provides insights into the design decisions, system components, and interactions specific to the Vulnerability management functionality.
+
+## Architecture overview
+
+The Vulnerability management architecture enables the identification, tracking, and remediation of software vulnerabilities across a fleet of devices. It compares installed software versions with known vulnerabilities and provides information about affected devices.
+
+To learn more, read our [vulnerability processing](https://fleetdm.com/guides/vulnerability-processing), [software filtering](https://fleetdm.com/guides/filtering-software-by-vulnerability), and [remediating the xz vulnerability with Fleet](https://fleetdm.com/guides/remediating-the-xz-vulnerability-with-fleet).
+
+## Key components
+
+## Architecture diagram
+
+```
+[Placeholder for Vulnerability Management Architecture Diagram]
+```
+
+## Vulnerability identification flow
+
+## Vulnerability data sources
+
+## Vulnerability scoring
+
+## Vulnerability remediation
+
+## Integration with external systems
+
+## Related resources
+
+- [Vulnerability processing guide]((https://fleetdm.com/guides/vulnerability-processing))
+- [Software filtering guide]((https://fleetdm.com/guides/filtering-software-by-vulnerability))
+- [Remediating the cx vulnerability with Fleet guide]((https://fleetdm.com/guides/remediating-the-xz-vulnerability-with-fleet))
+- [Software Product Group Documentation](../../product-groups/software/) - Documentation for the Software product group
+- [Software Development Guides](../../guides/software/) - Guides for Software development

docs/Contributing/getting-started/README.md

@@ -0,0 +1,28 @@
+# Getting Started with Fleet Development
+
+This directory contains documentation to help you get started with Fleet development.
+
+## Setting Up Your Development Environment
+
+- [Building Fleet](building-fleet.md) - Instructions for building Fleet from source
+- [Testing and Local Development](testing-and-local-development.md) - Guide for testing and local development
+- [Run Locally Built Fleetd](run-locally-built-fleetd.md) - Guide for running a locally built fleetd
+
+## Next Steps
+
+Once you have your development environment set up, you can explore the following resources:
+
+- [Guides](../guides/README.md) - How-to guides for common tasks
+- [Architecture](../architecture/README.md) - High-level architecture documentation
+- [Workflows](../workflows/README.md) - Development workflows
+- [Reference](../reference/README.md) - API reference, configuration, etc.
+
+## Product Groups
+
+Fleet is organized into three main product groups:
+
+- [MDM](../product-groups/mdm/README.md) - Mobile Device Management
+- [Orchestration](../product-groups/orchestration/README.md) - Device orchestration using osquery
+- [Software](../product-groups/software/README.md) - Software inventory, vulnerability management, and software installation
+
+Each product group has its own documentation, guides, and architecture documentation.

docs/Contributing/guides/README.md

@@ -0,0 +1,36 @@
+# Fleet development guides
+
+This directory contains guides for common development tasks in Fleet.
+
+## General guides
+
+- [Seeding Data](seeding-data.md) - Guide for seeding data in Fleet
+- [Committing Changes](committing-changes.md) - Guide for committing changes to Fleet
+- [Fleetctl Apply](cli/fleetctl-apply.md) - Guide for using fleetctl apply
+- [Simulate Slow Network](simulate-slow-network.md) - Guide for simulating a slow network
+- [Troubleshooting Live Queries](troubleshooting-live-queries.md) - Guide for troubleshooting live queries
+- [Enroll hosts with plain osquery](enroll-hosts-with-plain-osquery.md) - Guide for enrolling hosts with plain osquery
+- [Upcoming activities](upcoming-activities.md) - Guide for managing upcoming host activities
+
+## UI development
+
+- [Fleet UI Testing](ui/fleet-ui-testing.md) - Guide for testing the Fleet UI
+- [Generating UI Component Boilerplate](ui/generating-ui-component-boilerplate.md) - Guide for generating UI component boilerplate
+- [Design QA Considerations](ui/design-qa-considerations.md) - Guide for design QA considerations
+
+## API development
+
+- [Adding New Endpoints](api/adding-new-endpoints.md) - Guide for adding new endpoints to the Fleet API
+
+## Integration guides
+
+- [SCIM Integration](integrations/scim-integration.md) - Guide for integrating Fleet with SCIM
+- [Digicert Integration](integrations/digicert-integration.md) - Guide for integrating Fleet with Digicert
+
+## Product group guides
+
+Each product group has its own set of guides:
+
+- [MDM Guides](mdm/README.md) - Guides for MDM development
+- [Orchestration Guides](orchestration/README.md) - Guides for Orchestration development
+- [Software Guides](software/README.md) - Guides for Software development

docs/Contributing/guides/api/README.md

@@ -0,0 +1,14 @@
+# Fleet API Development Guides
+
+This directory contains guides for API development in Fleet.
+
+## API Development
+
+- [Adding New Endpoints](adding-new-endpoints.md) - Guide for adding new endpoints to the Fleet API
+
+## Related Resources
+
+- [API Versioning](../../reference/api-versioning.md) - Documentation on API versioning
+- [API for Contributors](../../reference/api-for-contributors.md) - Workflow for API development
+- [Workflows](../../workflows/README.md) - Development workflows
+- [Reference](../../reference/README.md) - API reference, configuration, etc.

docs/Contributing/guides/cli/README.md

@@ -0,0 +1,13 @@
+# Fleet CLI Development Guides
+
+This directory contains guides for CLI development in Fleet.
+
+## CLI Development
+
+- [Fleetctl Apply](cli/fleetctl-apply.md) - Guide for using fleetctl apply
+
+## Related Resources
+
+- [API for Contributors](../../reference/api-for-contributors.md) - Workflow for API development
+- [Workflows](../../workflows/README.md) - Development workflows
+- [Reference](../../reference/README.md) - API reference, configuration, etc.

docs/Contributing/guides/integrations/README.md

@@ -0,0 +1,14 @@
+# Fleet Integration Guides
+
+This directory contains guides for integrating Fleet with external systems.
+
+## Integration Guides
+
+- [SCIM Integration](scim-integration.md) - Guide for integrating Fleet with SCIM
+- [Digicert Integration](digicert-integration.md) - Guide for integrating Fleet with Digicert
+
+## Related Resources
+
+- [MDM Product Group](../../product-groups/mdm/README.md) - Documentation for the MDM product group
+- [Orchestration Product Group](../../product-groups/orchestration/README.md) - Documentation for the Orchestration product group
+- [Software Product Group](../../product-groups/software/README.md) - Documentation for the Software product group

docs/Contributing/guides/ui/README.md

@@ -0,0 +1,14 @@
+# Fleet UI Development Guides
+
+This directory contains guides for UI development in Fleet.
+
+## UI Development
+
+- [Fleet UI Testing](fleet-ui-testing.md) - Guide for testing the Fleet UI
+- [Generating UI Component Boilerplate](generating-ui-component-boilerplate.md) - Guide for generating UI component boilerplate
+- [Design QA Considerations](design-qa-considerations.md) - Guide for design QA considerations
+
+## Related Resources
+
+- [Workflows](../../workflows/README.md) - Development workflows
+- [Reference](../../reference/README.md) - API reference, configuration, etc.

docs/Contributing/product-groups/README.md

@@ -0,0 +1,47 @@
+# Fleet product groups
+
+Fleet is organized into three main product groups:
+
+## MDM
+
+The [MDM product group](mdm/README.md) focuses on Mobile Device Management, including:
+
+- Apple MDM (macOS, iOS)
+- Windows MDM
+- Android MDM
+- End user authentication
+- Disk encryption
+- Automated device enrollment
+
+## Orchestration
+
+The [Orchestration product group](orchestration/README.md) focuses on device orchestration using osquery, including:
+
+- Live queries
+- Scheduled queries
+- Query packs
+- Host vitals
+- Teams and access control
+- File carving
+- Policies
+- Scripts
+
+## Software
+
+The [Software product group](software/README.md) focuses on software management, including:
+
+- Software inventory
+- Vulnerability management
+- Software installation
+- Software updates
+- Software policies
+- Fleet-maintained apps
+
+## Cross-Product Documentation
+
+Some documentation applies to multiple product groups:
+
+- [Architecture](../architecture/README.md) - High-level architecture documentation
+- [Guides](../guides/README.md) - How-to guides for common tasks
+- [Workflows](../workflows/README.md) - Development workflows
+- [Reference](../reference/README.md) - API reference, configuration, etc.

docs/Contributing/product-groups/mdm/README.md

@@ -0,0 +1,22 @@
+# MDM (Mobile Device Management)
+
+This directory contains documentation specific to Fleet's Mobile Device Management (MDM) product group.
+
+## Overview
+
+Fleet's MDM functionality allows organizations to manage and secure devices across different platforms, including Apple (macOS, iOS) and Windows.
+
+## Contents
+
+- [MDM Overview](mdm-overview.md)
+- [End User Authentication](mdm-end-user-authentication.md)
+- [Apple Account Driven User Enrollment](apple-account-driven-user-enrollment.md)
+- [Android MDM](android-mdm.md)
+- [Windows MDM Glossary and Protocol](windows-mdm-glossary-and-protocol.md)
+- [Custom Configuration Web URL](custom-configuration-web-url.md)
+- [Custom SCEP Integration](custom-scep-integration.md)
+- [Provide end user email address w/o relying on end user](set-up-custom-end-user-email.md)
+
+## Related Resources
+
+- [MDM Architecture](../../architecture/mdm/)

docs/Contributing/product-groups/orchestration/README.md

@@ -0,0 +1,18 @@
+# Orchestration
+
+This directory contains documentation specific to Fleet's Orchestration product group.
+
+## Overview
+
+Fleet's Orchestration functionality allows organizations to manage and query devices at scale using osquery, providing visibility into device status, configuration, and security posture.
+
+## Contents
+
+- [Understanding Host Vitals](understanding-host-vitals.md)
+- [Teams](teams.md)
+- [File Carving](file-carving.md)
+
+## Related Resources
+
+- [Orchestration Architecture](../../architecture/orchestration/)
+- [Troubleshooting Live Queries](../../guides/troubleshooting-live-queries.md)

docs/Contributing/product-groups/software/README.md

@@ -0,0 +1,14 @@
+# Software
+
+This directory contains documentation specific to Fleet's Software product group.
+
+## Overview
+
+Fleet's Software functionality allows organizations to manage software across their device fleet, including software inventory, vulnerability management, and software installation.
+
+## Contents
+
+
+## Related Resources
+
+- [Software Architecture](../../architecture/software/)

docs/Contributing/reference/README.md

@@ -0,0 +1,19 @@
+# Fleet reference documentation
+
+This directory contains reference documentation for Fleet.
+
+## API reference
+
+- [API for contributors](api-for-contributors.md) - API reference for contributors
+
+## Configuration
+
+- [Configuration for contributors](configuration-for-contributors.md) - Configuration reference for contributors
+
+## Development patterns
+
+- [Backend patterns](patterns-backend.md) - Common patterns for backend development
+
+## FAQ
+
+- [FAQ](faq.md) - Frequently asked questions

docs/Contributing/reference/configuration-for-contributors.md

@@ -5,7 +5,7 @@
 
 This document includes Fleet server configuration settings that are helpful when developing or contributing to Fleet.
 
-Unlike the [fleetctl apply format](https://github.com/fleetdm/fleet/tree/main/docs/Contributing/fleetctl-apply.md), the files and settings in this document are not recommended for production use. Each setting includes the best practice for being successful in production.
+Unlike the [fleetctl apply format](https://github.com/fleetdm/fleet/tree/main/docs/Contributing/guides/fleetctl-apply.md), the files and settings in this document are not recommended for production use. Each setting includes the best practice for being successful in production.
 
 ## Fleet server configuration
 

docs/Contributing/research/README.md

@@ -0,0 +1,21 @@
+# Fleet Research Documentation
+
+This directory contains research documents for Fleet product groups.
+
+## Product Group Research
+
+Each product group has its own research documentation:
+
+- [MDM Research](mdm/) - Research documentation for MDM
+- [Orchestration Research](orchestration/) - Research documentation for Orchestration
+- [Software Research](software/) - Research documentation for Software
+
+## Purpose
+
+Research documents capture exploration, investigation, and analysis of potential features, technologies, or approaches. They help inform architectural decisions and product direction.
+
+## Related Resources
+
+- [Architecture](../architecture/README.md) - High-level architecture documentation
+- [Product Groups](../product-groups/README.md) - Documentation for specific product groups
+- [ADRs](../adr/README.md) - Architectural Decision Records

docs/Contributing/responsibilities/README.md

@@ -0,0 +1,21 @@
+# Fleet Responsibilities Documentation
+
+This directory contains responsibility documents for Fleet product groups.
+
+## Product Group Responsibilities
+
+Each product group has its own responsibility documentation:
+
+- [MDM Responsibilities](mdm/) - Responsibility documentation for MDM
+- [Orchestration Responsibilities](orchestration/) - Responsibility documentation for Orchestration
+- [Software Responsibilities](software/) - Responsibility documentation for Software
+
+## Purpose
+
+Responsibility documents define the scope, ownership, and boundaries of each product group. They help clarify which team is responsible for which parts of the system, reducing overlap and ensuring all aspects of the system are covered.
+
+## Related Resources
+
+- [Product Groups](../product-groups/README.md) - Documentation for specific product groups
+- [Architecture](../architecture/README.md) - High-level architecture documentation
+- [Research](../research/README.md) - Research documents for product groups

docs/Contributing/workflows/README.md

@@ -0,0 +1,17 @@
+# Fleet Development Workflows
+
+This directory contains documentation on common development workflows in Fleet.
+
+## Release Workflows
+
+- [Releasing Fleet](releasing-fleet.md) - Workflow for releasing Fleet
+- [Fleetd Development and Release Strategy](fleetd-development-and-release-strategy.md) - Workflow for developing and releasing fleetd
+
+## Testing Workflows
+
+- [Deploying Chrome Test Extension](deploying-chrome-test-ext.md) - Workflow for deploying the Chrome test extension
+- [Fleet UI Testing](../guides/ui/fleet-ui-testing.md) - Workflow for testing the Fleet UI
+
+## Dependency Management
+
+- [Upgrading Go Version](upgrading-go-version.md) - Workflow for upgrading the Go version

docs/Contributing/workflows/upgrading-go-version.md

@@ -30,7 +30,7 @@ Do a search for go.mod files to find others that may need updating!
 
 The golangci-lint linter used in the [golangci-lint](https://github.com/fleetdm/fleet/actions/workflows/golangci-lint.yml) Github action needs to support the new version of Go.  The linter typically keeps up with Go versions so that the latest version of golangci-lint should support the latest version of Go, but it's worth checking the [changelog](https://github.com/golangci/golangci-lint/blob/main/CHANGELOG.md) to see if it's time for an upgrade. If so, get the commit SHA of the version you'd like to use by finding [its tag on Github](https://github.com/golangci/golangci-lint/tags), clicking on the commit link under the tag name, and copying the full SHA from the URL.  Update the current `go install github.com/golangci/golangci-lint/cmd/golangci-lint` line in the .yml file with the new SHA, and update the comment to indicate the new version. 
 
-Update the instructions in the [Testing and local development doc](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Testing-and-local-development.md#test-suite) to reflect the new version of golangci-lint.
+Update the instructions in the [Testing and local development doc](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/getting-started/testing-and-local-development.md#test-suite) to reflect the new version of golangci-lint.
 
 ### Docker files
 

docs/REST API/rest-api.md

@@ -574,7 +574,7 @@ Fleet supports osquery's file carving functionality as of Fleet 3.3.0. This allo
 
 To initiate a file carve using the Fleet API, you can use the [live query](#run-live-query) endpoint to run a query against the `carves` table.
 
-For more information on executing a file carve in Fleet, go to the [File carving with Fleet docs](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/File-carving.md).
+For more information on executing a file carve in Fleet, go to the [File carving with Fleet docs](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/product-groups/orchestration/file-carving.md).
 
 ### List carves
 

frontend/README.md

@@ -12,11 +12,11 @@ The Fleet frontend is a Single Page Application using React with Typescript and
 ## Running the Fleet web app
 
 For details instruction on building and serving the Fleet web application
-consult the [Contributing documentation](../docs/Contributing/README.md).
+consult the [Contributing documentation](../docs/Contributing/getting-started/README.md).
 
 ## Testing
 
-Visit the [overview of Fleet UI testing](../docs/Contributing/Fleet-UI-Testing.md) for more information on our testing strategy, philosophies, and tools.
+Visit the [overview of Fleet UI testing](../docs/Contributing/guides/ui/fleet-ui-testing.md) for more information on our testing strategy, philosophies, and tools.
 
 To run unit or integration tests in `ComponentName.tests.tsx`, run `yarn test -- ComponentName.tests.tsx`. To [test all Javascript components](https://fleetdm.com/docs/contributing/testing-and-local-development#javascript-unit-tests) run `yarn test`.
 

frontend/__mocks__/README.md

@@ -48,8 +48,8 @@ Use the helper function with arguments to override the default mock data with th
 
 Check out the [frontend test directory](../test/README.md) for information about our unit and integration testing layers. We use default mocks and custom mocks when [mocking server requests](../test/README.md#server-handlers).
 
-Follow [this guide](../../docs/Contributing/Testing-and-local-development.md) to run tests locally.
+Follow [this guide](../../docs/Contributing/getting-started/testing-and-local-development.md) to run tests locally.
 
-Visit the frontend [overview of Fleet UI testing](../docs/Contributing/Fleet-UI-Testing.md) for more information on our testing strategy, philosophies, and tools.
+Visit the frontend [overview of Fleet UI testing](../docs/Contributing/guides/ui/fleet-ui-testing.md) for more information on our testing strategy, philosophies, and tools.
 
 

frontend/services/entities/scripts.ts

@@ -69,7 +69,7 @@ export interface IHostScriptsResponse {
 /**
  * Request body for POST /scripts/run
  *
- * https://github.com/fleetdm/fleet/blob/main/docs/Contributing/API-for-contributors.md#run-script-asynchronously
+ * https://github.com/fleetdm/fleet/blob/main/docs/Contributing/reference/api-for-contributors.md#run-script-asynchronously
  */
 export interface IScriptRunRequest {
   host_id: number;
@@ -80,7 +80,7 @@ export interface IScriptRunRequest {
 /**
  * Response body for POST /scripts/run
  *
- * https://github.com/fleetdm/fleet/blob/main/docs/Contributing/API-for-contributors.md#run-script-asynchronously
+ * https://github.com/fleetdm/fleet/blob/main/docs/Contributing/reference/api-for-contributors.md#run-script-asynchronously
  */
 export interface IScriptRunResponse {
   host_id: number;

frontend/test/README.md

@@ -40,6 +40,6 @@ Testing stubs are still being used in a handful of old tests. We are no longer f
 
 Check out how we [mock data](../__mocks__/README.md) used for unit and integration tests.
 
-Follow [this guide](../../docs/Contributing/Testing-and-local-development.md) to run tests locally.
+Follow [this guide](../../docs/Contributing/getting-started/testing-and-local-development.md) to run tests locally.
 
-Visit the frontend [overview of Fleet UI testing](../docs/Contributing/Fleet-UI-Testing.md) for more information on our testing strategy, philosophies, and tools.
+Visit the frontend [overview of Fleet UI testing](../docs/Contributing/guides/ui/fleet-ui-testing.md) for more information on our testing strategy, philosophies, and tools.