diff --git a/README.md b/README.md
index cb00af79..3accb986 100644
--- a/README.md
+++ b/README.md
@@ -58,9 +58,36 @@ make lint         # run static analysis
 ├── cmd/goboxd/   binary entry point
 ├── internal/     private application packages
 ├── docs/         api, languages, security, benchmarks, architecture
+
 └── tests/        integration tests
 ```
 
+
+## How It Works
+
+1. A user sends source code through an HTTP request.
+2. The service creates an isolated sandbox.
+3. The code is compiled and executed safely.
+4. Resource limits are enforced.
+5. Execution results are returned to the user.
+
+## Security Features
+
+- Linux namespaces
+- cgroups isolation
+- Resource limits
+- Bounded concurrency
+- Containerized execution
+
+## Future Improvements
+
+- Support additional programming languages
+- Web dashboard
+- Authentication and authorization
+- Execution history
+- Kubernetes deployment
+
+
 ## Contributing
 
 Contributions are welcome. Open an issue to discuss substantial changes before sending a pull request.
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 00000000..68c7470a
--- /dev/null
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,27 @@
+# Architecture
+
+## Request Flow
+
+User
+  ↓
+HTTP API
+  ↓
+Sandbox Manager
+  ↓
+Language Runtime
+  ↓
+Execution Result
+
+## Components
+
+### HTTP API
+Receives execution requests.
+
+### Sandbox Manager
+Creates isolated execution environments.
+
+### Language Runtime
+Compiles and executes code.
+
+### Result Handler
+Returns output and errors.