docs: project structure (#467)

docs/SUMMARY.md

@@ -9,9 +9,11 @@
 
 * [Overview](ten_agent/overview.md)
 * [Getting Started](ten_agent/getting_started.md)
+* [Architecture](ten_agent/architecture_flow.md)
 * [Project Structure](ten_agent/project_structure/overview.md)
   * [Understand property.json](ten_agent/project_structure/property_json.md)
   * [Understand extension folder](ten_agent/project_structure/extension.md)
+  * [Understand web server](ten_agent/project_structure/server.md)
 * [Run Demo](ten_agent/demo/quickstart.md)
 * [Run Playground](ten_agent/playground/quickstart.md)
   * [Configure Modules](ten_agent/playground/configure_modules.md)

docs/ten_agent/architecture_flow.md

@@ -0,0 +1,11 @@
+# Architecture Flow
+
+The whole system contains multiple components that work together to provide a seamless experience. The main components are:
+
+- **TEN Agent App**: The main application that orchestrates the extensions and manages the data flow between them. It runs as a background process. Depending on the graph configuration, the agent starts the required extensions and handles the data flow between them.
+- **Front-end UI**: A web-based interface to interact with the agent. It allows users to configure the agent, start/stop the agent, and talk to the agent.
+- **Web Server**: A simple Golang web server that serves the HTTP requests. It is responsible for handling the incoming requests and starting/stopping agent processes. It also passes parameter like `graph_name` to determine which graph to use.
+
+The flow of the system is as follows:
+
+![Architecture Flow](https://github.com/TEN-framework/docs/blob/main/assets/png/architecture_flow.png?raw=true)

docs/ten_agent/project_structure/overview.md

@@ -11,4 +11,4 @@ It contains the following important folders and files:
 - `property.json`: This file contains the orchestration of extensions. It is the main runtime configuration file.
 - `ten_packages/extension`: This folder contains the extension modules. Each extension module is a separate Python/Golang/C++ package.
 - `server`: This folder contains the web server code. It is responsible for handling the incoming requests and start/stop of agent processes.
-- `playground`: This folder contains the UI code for the playground. It is a web-based interface to interact with the agent.
+- `playground`: This folder contains the UI code for the playground. It is a web-based interface to interact with the agent.

docs/ten_agent/project_structure/property_json.md

@@ -7,6 +7,10 @@ This file contains the orchestration of extensions. It is the main runtime confi
 
 The `property.json` file contains the following orchestration info,
 
+- Graphs
+- Nodes
+- Connections
+
 ## Graphs
 
 The `predefined_graphs` property contains a list of available graphs. Each graph defines how agent should behave in a specific scenario. Each graph has a `name` property which is used to identify a graph.

docs/ten_agent/project_structure/server.md

@@ -0,0 +1,88 @@
+# Web Server
+
+The web server is a simple Golang web server that serves the http requests. It is responsible for handling the incoming requests and starting/stopping agent processes.
+
+The playground/demo UI has been built to interact with the web server. You can also interact with the web server using curl or any other http client.
+
+## Request & Response Examples
+
+The server provides a simple layer for managing agent processes. The API resources are described below.
+
+### API Resources
+
+- [POST /start](#post-start)
+- [POST /stop](#post-stop)
+- [POST /ping](#post-ping)
+
+### POST /start
+
+This api starts an agent with given graph and override properties. The started agent will join into the specified channel, and subscribe to the uid which your browser/device's rtc use to join.
+
+| Param    | Description |
+| -------- | ------- |
+| request_id  | any uuid for tracing purpose    |
+| channel_name | channel name, it needs to be the same with the one your browser/device joins, agent needs to stay with your browser/device in the same channel to communicate  |
+| user_uid    | the uid which your browser/device's rtc use to join, agent needs to know your rtc uid to subscribe your audio    |
+| bot_uid    | optional, the uid bot used to join rtc    |
+| graph_name    | the graph to be used when starting agent, will find in property.json    |
+| properties    | additional properties to override in property.json, the override will not change original property.json, only the one agent used to start    |
+| timeout | determines how long the agent will remain active without receiving any pings. If the timeout is set to `-1`, the agent will not terminate due to inactivity. By default, the timeout is set to 60 seconds, but this can be adjusted using the `WORKER_QUIT_TIMEOUT_SECONDS` variable in your `.env` file. |
+
+Example:
+
+```bash
+curl 'http://localhost:8080/start' \
+  -H 'Content-Type: application/json' \
+  --data-raw '{
+    "request_id": "c1912182-924c-4d15-a8bb-85063343077c",
+    "channel_name": "test",
+    "user_uid": 176573,
+    "graph_name": "camera_va_openai_azure",
+    "properties": {
+      "openai_chatgpt": {
+        "model": "gpt-4o"
+      }
+    }
+  }'
+```
+
+### POST /stop
+
+This api stops the agent you started
+
+| Param    | Description |
+| -------- | ------- |
+| request_id  | any uuid for tracing purpose    |
+| channel_name | channel name, the one you used to start the agent  |
+
+Example:
+
+```bash
+curl 'http://localhost:8080/stop' \
+  -H 'Content-Type: application/json' \
+  --data-raw '{
+    "request_id": "c1912182-924c-4d15-a8bb-85063343077c",
+    "channel_name": "test"
+  }'
+```
+
+
+### POST /ping
+
+This api sends a ping to the server to indicate connection is still alive. This is not needed if you specify `timeout:-1` when starting the agent, otherwise the agent will quit if not receiving ping after timeout in seconds.
+
+| Param    | Description |
+| -------- | ------- |
+| request_id  | any uuid for tracing purpose    |
+| channel_name | channel name, the one you used to start the agent  |
+
+Example:
+
+```bash
+curl 'http://localhost:8080/ping' \
+  -H 'Content-Type: application/json' \
+  --data-raw '{
+    "request_id": "c1912182-924c-4d15-a8bb-85063343077c",
+    "channel_name": "test"
+  }'
+```