From bdb18edfbd7f6d27c446937346c490962de68e22 Mon Sep 17 00:00:00 2001
From: Javier Marcos <1271349+javuto@users.noreply.github.com>
Date: Tue, 24 Feb 2026 12:23:33 +0100
Subject: [PATCH 1/3] Updated README with file structure and flowchart

---
 README.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)

diff --git a/README.md b/README.md
index c811f00e..7b581146 100644
--- a/README.md
+++ b/README.md
@@ -42,6 +42,63 @@ Whether you’re running a small deployment or managing large fleets, **osctrl**
 
 You can find the documentation of the project in [https://osctrl.net](https://osctrl.net)
 
+## 🗂 Project Structure
+
+```text
+osctrl/
+├── cmd/                         # Service and CLI entrypoints
+│   ├── admin/                   # osctrl-admin (web UI + admin handlers/templates/static)
+│   ├── api/                     # osctrl-api (REST API service)
+│   ├── cli/                     # osctrl-cli (operator CLI)
+│   └── tls/                     # osctrl-tls (osquery remote API endpoint)
+├── pkg/                         # Shared application packages
+│   ├── auditlog/                # Audit log manager
+│   ├── backend/                 # DB manager/bootstrap
+│   ├── cache/                   # Redis/cache managers
+│   ├── carves/                  # File carve logic/storage integrations
+│   ├── config/                  # Config structs/flags/validation
+│   ├── environments/            # Environment management
+│   ├── handlers/                # Shared HTTP handlers
+│   ├── logging/                 # Log pipeline + logger backends
+│   ├── nodes/                   # Node state/registration/cache
+│   ├── queries/                 # Query management/scheduling/results
+│   ├── settings/                # Runtime settings
+│   ├── tags/                    # Tag management
+│   ├── users/                   # User and permissions management
+│   ├── utils/                   # Utility helpers
+│   └── version/                 # Version metadata
+├── deploy/                      # Deployment configs/scripts (docker, nginx, cicd, osquery, systemd)
+├── tools/                       # Dev/release helpers and API test assets (Bruno collections, scripts)
+├── bin/                         # Built binaries (from make)
+├── docker-compose-dev.yml       # Local multi-service development stack
+├── Makefile                     # Build/test/dev targets
+└── osctrl-api.yaml              # OpenAPI specification for osctrl-api
+```
+
+## 🏛 Architecture
+
+```mermaid
+flowchart LR
+    A["osquery Agents"] -->|TLS Remote API| T["osctrl-tls"]
+    O["Operators"] -->|Web UI| W["osctrl-admin"]
+    O -->|CLI| C["osctrl-cli"]
+    O -->|REST| P["osctrl-api"]
+
+    W -->|HTTP API| P
+    C -->|HTTP API| P
+
+    T --> S["Shared Packages (pkg/*)"]
+    W --> S
+    P --> S
+    C --> S
+    C -.->|Direct DB mode| D
+
+    S --> D["PostgreSQL Backend"]
+    S --> R["Redis Cache"]
+    S --> L["Log Destinations (DB, file, S3, Elastic, Splunk, Graylog, Kafka, Kinesis, Logstash)"]
+    S --> F["Carve Storage (DB, local, S3)"]
+```
+
 ## 🛠 Development
 
 The fastest way to get started with **osctrl** development is by using [Docker](https://www.docker.com/) and [Docker Compose](https://docs.docker.com/compose/). But you can find other methods below.

From d5c68ff674b791f8463d98b32dabf1f540d1522d Mon Sep 17 00:00:00 2001
From: Javier Marcos <1271349+javuto@users.noreply.github.com>
Date: Tue, 24 Feb 2026 12:54:46 +0100
Subject: [PATCH 2/3] Update README.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 7b581146..1fafbc28 100644
--- a/README.md
+++ b/README.md
@@ -67,7 +67,7 @@ osctrl/
 │   ├── users/                   # User and permissions management
 │   ├── utils/                   # Utility helpers
 │   └── version/                 # Version metadata
-├── deploy/                      # Deployment configs/scripts (docker, nginx, cicd, osquery, systemd)
+├── deploy/                      # Deployment configs/scripts (docker/nginx/osquery/systemd, CI/CD, redis, config, helpers, etc.)
 ├── tools/                       # Dev/release helpers and API test assets (Bruno collections, scripts)
 ├── bin/                         # Built binaries (from make)
 ├── docker-compose-dev.yml       # Local multi-service development stack

From 5a344ba57f9b7415314056e9982f71fcfa27df9b Mon Sep 17 00:00:00 2001
From: Javier Marcos <1271349+javuto@users.noreply.github.com>
Date: Tue, 24 Feb 2026 12:55:03 +0100
Subject: [PATCH 3/3] Update README.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/README.md b/README.md
index 1fafbc28..a5ab61f2 100644
--- a/README.md
+++ b/README.md
@@ -66,6 +66,7 @@ osctrl/
 │   ├── tags/                    # Tag management
 │   ├── users/                   # User and permissions management
 │   ├── utils/                   # Utility helpers
+│   ├── types/                   # Shared type definitions
 │   └── version/                 # Version metadata
 ├── deploy/                      # Deployment configs/scripts (docker/nginx/osquery/systemd, CI/CD, redis, config, helpers, etc.)
 ├── tools/                       # Dev/release helpers and API test assets (Bruno collections, scripts)