Merge pull request #1891 from janhq/doc-improvs

General improvements and additions to the documentation.

Author: ramonpzg

.gitignore

@@ -21,4 +21,10 @@ platform/command
 platform/src/infrastructure/commanders/test/test_data
 **/vcpkg_installed
 engine/test.db
-!docs/yarn.lock
+!docs/yarn.lock
+
+# Local
+docs/.yarn/
+docs/.yarnrc.yml
+docs/bun.lockb
+docs/yarn.lock

docs/docs/architecture/cortex-db.mdx

@@ -8,18 +8,26 @@ import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
 :::warning
-🚧 Cortex.cpp is currently under development. Our documentation outlines the intended behavior of Cortex, which may not yet be fully implemented in the codebase.
+🚧 Cortex.cpp is currently under active development. Our documentation outlines the intended behavior
+of Cortex, which may not yet be fully implemented in the codebase.
 :::
 
-This document outlines the architecture of the database designed to store and manage various types of entities and their associated metadata.
+![sqlite-view](/img/sqlite_view_harlequin.png)
+**db view via [Harlequin](https://harlequin.sh/)**
+
+
+This document outlines Cortex database architecture which is designed to store and manage models, engines,
+files and more.
+
+## Tables Structure
 
-## Table Structure
 ### schema Table
+
 The `schema` table is designed to hold schema version for cortex database. Below is the structure of the table:
 
 | Column Name        | Data Type | Description                                             |
 |--------------------|-----------|---------------------------------------------------------|
-| schema_version     | INTEGER   | A unique schema version for database.                   |
+| version            | INTEGER   | A unique schema version for database.                   |
 
 ### models Table
 The `models` table is designed to hold metadata about various AI models. Below is the structure of the table:
@@ -49,3 +57,33 @@ The `hardware` table is designed to hold metadata about hardware information. Be
 | activated          | INTEGER   | A boolean value (0 or 1) indicating whether the hardware is activated or not. |
 | priority           | INTEGER   | An integer value representing the priority associated with the hardware. |
 
+
+### engines Table
+The `engines` table is designed to hold metadata about the different engines available for useage with Cortex.
+Below is the structure of the table:
+
+| Column Name  | Data Type | Description                                             |
+|--------------|-----------|---------------------------------------------------------|
+| id           | INTEGER   | A unique identifier for each engine (Primary Key).      |
+| engine_name  | TEXT      | The name of the engine. |
+| type         | TEXT      |  |
+| api_key      | TEXT      |  |
+| url          | TEXT      |  |
+| version      | TEXT      | The current version of the engine. |
+| variant      | TEXT      |  |
+| status       | TEXT      | Current status of the engine (e.g., "downloaded", "downloadable"). |
+| metadata     | TEXT      | Additional metadata or information about the engine. |
+| date_ceated  | TEXT      | Date when the engine was downloaded. |
+| date_updated | TEXT      | Date when the engine was last updated. |
+
+### files Table
+The `files` table is designed to hold metadata about objects dowloaded via Cortex.
+
+| Column Name | Data Type | Description                     |
+|-------------|-----------|---------------------------------|
+| id         | TEXT      | The primary key for the table    |
+| object     | TEXT      | The type of hardware.            |
+| purpose    | TEXT      | Purpose of file                  |
+| filename   | TEXT      | The name of the file.            |
+| created_at | INTEGER   | Date when file was created       |
+| bytes      | INTEGER   |                                  |

docs/docs/architecture/cortexrc.mdx

@@ -8,10 +8,13 @@ import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
 :::warning
-🚧 Cortex.cpp is currently under development. Our documentation outlines the intended behavior of Cortex, which may not yet be fully implemented in the codebase.
+🚧 Cortex.cpp is currently under active development. Our documentation outlines the intended behavior of
+Cortex, which may not be fully implemented in the codebase yet.
 :::
 
-Cortex.cpp supports reading its configuration from a file called `.cortexrc`. Using this file, you can also change the data folder, Cortex.cpp API server port, and host.
+Cortex supports using a config-based approach to configuring most of its functionality. During the
+installation process, a `.cortexrc` will be generated with some sensible defaults in it. Using this
+file, you can change the location and name of the data directory, the Cortex API server port, the host and more.
 
 ## File Location
 
@@ -31,25 +34,52 @@ You can configure the following parameters in the `.cortexrc` file:
 | `apiServerPort`  | Port number for the Cortex.cpp API server.       | `39281`                        |
 | `logFolderPath`  | Path the folder where logs are located           | User's home folder.            |
 | `logLlamaCppPath`  | The llama-cpp engine .                         | `./logs/cortex.log`            |
-| `logTensorrtLLMPath`  | The tensorrt-llm engine log file path.      | `./logs/cortex.log`            |
 | `logOnnxPath`    | The onnxruntime engine log file path.            | `./logs/cortex.log`            |
 | `maxLogLines`    | The maximum log lines that write to file.        | `100000`                       |
 | `checkedForUpdateAt`  | The last time for checking updates.         | `0`                            |
 | `latestRelease`  | The lastest release vesion.                      | Empty string                   |
 | `huggingFaceToken`  | HuggingFace token.                            | Empty string                   |
 
+
+In the future, every parameter will be editable from the Cortex CLI. At present, only a selected few are configurable.
+
 Example of the `.cortexrc` file:
 
 ```
-logFolderPath: /Users/<username>/cortexcpp
+logFolderPath: /home/<user>/cortexcpp
 logLlamaCppPath: ./logs/cortex.log
 logTensorrtLLMPath: ./logs/cortex.log
 logOnnxPath: ./logs/cortex.log
-dataFolderPath: /Users/<username>/cortexcpp
+dataFolderPath: /home/<user>/cortexcpp
 maxLogLines: 100000
 apiServerHost: 127.0.0.1
 apiServerPort: 39281
-checkedForUpdateAt: 1730501224
-latestRelease: v1.0.1
+checkedForUpdateAt: 1737636738
+checkedForLlamacppUpdateAt: 1737636592699
+latestRelease: v1.0.8
+latestLlamacppRelease: v0.1.49
 huggingFaceToken: ""
+gitHubUserAgent: ""
+gitHubToken: ""
+llamacppVariant: linux-amd64-avx2-cuda-12-0
+llamacppVersion: v0.1.49
+enableCors: true
+allowedOrigins:
+  - http://localhost:39281
+  - http://127.0.0.1:39281
+  - http://0.0.0.0:39281
+proxyUrl: ""
+verifyProxySsl: true
+verifyProxyHostSsl: true
+proxyUsername: ""
+proxyPassword: ""
+noProxy: example.com,::1,localhost,127.0.0.1
+verifyPeerSsl: true
+verifyHostSsl: true
+sslCertPath: ""
+sslKeyPath: ""
+supportedEngines:
+  - llama-cpp
+  - onnxruntime
+  - tensorrt-llm
 ```

docs/docs/architecture/data-folder.mdx

@@ -1,23 +1,25 @@
 ---
-title: Data Folder and App Folder
-description: Cortex.cpp's data folder and app folder.
+title: Data and App Directories
+description: Cortex's data and app directories.
 slug: "data-folder"
 ---
 
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
 :::warning
-🚧 Cortex.cpp is currently under development. Our documentation outlines the intended behavior of Cortex, which may not yet be fully implemented in the codebase.
+🚧 Cortex.cpp is currently under active development. Our documentation outlines the
+intended behavior of Cortex and some functionality may not be fully implemented yet.
 :::
 
 When you install Cortex.cpp, three types of files will be generated on your device:
 
 - **Binary Files**
 - **Configuration Files**
-- **Data Folder**
+- **A Data Directory**
 
 ## Binary Files - under the App Folder
+
 These are the executable files of the Cortex.cpp application. The file format varies depending on the operating system:
 
 - **Windows**:
@@ -30,53 +32,73 @@ These are the executable files of the Cortex.cpp application. The file format va
   - cli: `/usr/local/bin/cortex`
   - server: `/usr/local/bin/cortex-server`
 
-## Cortex.cpp Data Folder
-The data folder stores the engines, models, and logs required by Cortex.cpp. This folder is located at:
+## Cortex Data Directory
+
+The data DIRECTORY stores the engines, models used by Cortex and the logs generated by the
+server and CLI. The data directory is located at:
 
 - **Windows**: `C:\Users\<username>\cortexcpp`
 - **Linux**: `/home/<username>/cortexcpp`
 - **macOS**: `/Users/<username>\cortexcpp`
 
-### Folder Structure
-The Cortex.cpp data folder typically follows this structure:
-
-<Tabs>
-  <TabItem value="Stable" label="Stable">
-  ```yaml
-  ~/.cortex
-    ├── models/
-    │   └── model.list
-    │   └── huggingface.co/
-    │       └── <repo_name>/
-              └── <branch_name>/
-                └── model.yaml
-                └── model.gguf
-    │   └── cortex.so/
-    │       └── <repo_name>/
-    │         └── <branch_name>/
-                └── ...engine_files
-                └── model.yaml
-    │   └── imported/
-            └── imported_model.yaml
-    ├── logs/
-    │   └── cortex.txt
-        └── cortex-cli.txt
-    └── engines/
-        └── llamacpp
-  ```
-  </TabItem>
-</Tabs>
-
-#### `cortexcpp`
-The main directory that stores all Cortex-related files, located in the user's home directory.
+### Directory Structure
+
+The Cortex data directory can be found in the user's home directory, and
+it typically follows the structure below:
+
+```
+~/cortexcpp
+├── cortex.db
+├── engines/
+│   ├── cortex.llamacpp/
+│   ├── deps/
+│   │   ├── libcublasLt.so.12
+│   │   └── libcudart.so.12
+│   └── linux-amd64-avx2-cuda-12-0/
+│       └── ...
+├── files
+├── logs/
+│   ├── cortex-cli.log
+│   └── cortex.log
+├── models/
+│   ├── cortex.so/
+│   │   ├── deepseek-r1-distill-llama-8b/
+│   │   │   └── 8b-gguf-q2-k/
+│   │   │       ├── metadata.yml
+│   │   │       ├── model.gguf
+│   │   │       └── model.yml
+│   │   └── ...
+│   └── huggingface.co/
+│       ├── bartowski/
+│       │   └── phi-4-GGUF/
+│       │       ├── phi-4-Q3_K_S.gguf
+│       │       └── phi-4-Q3_K_S.yml
+│       └── unsloth/
+│           └── DeepSeek-R1-Distill-Qwen-1.5B-GGUF/
+│               ├── DeepSeek-R1-Distill-Qwen-1.5B-Q4_K_M.gguf
+│               └── DeepSeek-R1-Distill-Qwen-1.5B-Q4_K_M.yml
+└── threads
+```
+
 #### `models/`
-Contains the AI models used by Cortex for processing and generating responses.
+
+Contains all of the models used by Cortex for processing and generating responses. These models can come from
+anywhere in the HuggingFace model Hub or the Cortex model Hub.
+
 :::info
 For more information regarding the `model.list` and `model.yaml`, please see [here](/docs/capabilities/models/model-yaml).
 :::
+
 #### `logs/`
-Stores log files that are essential for troubleshooting and monitoring the performance of the Cortex.cpp API server and CLI.
 
-We use Trantor for logging, which ensures non-blocking, thread-safe, multi-stream file logging without affecting system performance. Trantor automatically creates a new log file for each server session, based on the date and time, simplifying debugging. It also supports setting limits on log file size and the number of log files per session.
+Stores log files from the Cortex server and CLI. These are essential for troubleshooting and
+monitoring performance.
+
+We use [Trantor](https://github.com/an-tao/trantor) for logging, which ensures non-blocking, thread-safe,
+and multi-stream file logging without affecting your system's performance. Trantor automatically creates a
+new log file for each server session based on the date and time, simplifying debugging. It also supports
+setting limits on log file size and the number of log files per session.
+
 #### `engines/`
-Stores the necessary dependencies and engine files needed to run Cortex on supported engines.
+
+Stores the necessary dependencies and engine files needed to run run models on via the supported engines.

docs/docs/architecture/updater.mdx

@@ -8,14 +8,17 @@ import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
 :::warning
-🚧 Cortex.cpp is currently under development. Our documentation outlines the intended behavior of Cortex, which may not yet be fully implemented in the codebase.
+🚧 Cortex.cpp is currently under active development. Our documentation outlines the intended behavior of
+Cortex, which may not yet be fully implemented in the codebase.
 :::
 
-This document outlines the architectural design for a C++ updater responsible for downloading and executing installers for two binaries: CLI and Server. 
+This document outlines the architectural design for a C++ updater responsible for downloading and executing
+the installers for the CLI and Server binaries.
 
 ## Overview
 
-The updater is designed to check for available updates, download the necessary installer files, and execute them to update the CLI and Server binaries. The architecture consists of several key components that work together to achieve this functionality.
+The updater is designed to check for available updates, download the necessary installer files, and execute
+them to update the CLI and Server binaries.
 
 ## Components
 
@@ -24,7 +27,7 @@ The updater is designed to check for available updates, download the necessary i
 - **Purpose**: Responsible for checking the current version of the installed binaries and determining if updates are available.
 - **Responsibilities**:
   - Retrieve the current version from local installations.
-  - Fetch the latest version information from a remote source, latest version information is saved to `.cortexrc`.
+  - Fetch information regarding the latest version from a remote source and save such info in `.cortexrc`.
   - Determine if an update is necessary based on version comparison.
 
 ### 2. **Installer Download Manager**
@@ -61,7 +64,8 @@ The updater is designed to check for available updates, download the necessary i
    - It fetches the latest version information from a remote source.
 
 3. **Update Decision**:
-   - If newer versions are available, the updater proceeds to download the installers; otherwise, it informs the user that no updates are necessary.
+   - If newer versions are available, the updater proceeds to download the installers; otherwise, it informs the
+   user that no updates are necessary.
 
 4. **Download Process**:
    - The Installer Download Manager downloads the latest installer files using HTTP requests.
@@ -72,5 +76,6 @@ The updater is designed to check for available updates, download the necessary i
    - It monitors the installation process, capturing any output or errors.
 
 6. **Completion Notification**:
-   - After successful installation, the User Interface notifies users of completion or any issues encountered during installation.
-   - Logs are updated with relevant information about the update process.
+   - After successful installation, the User Interface notifies users of completion or any issues encountered
+   during installation.
+   - Logs are updated with relevant information about the update process.