Adding docs (#5)

* adding docs
* updated readme

Author: HardMax71

.github/workflows/docs.yml

@@ -0,0 +1,145 @@
+name: docs
+
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - 'docs/**'
+      - 'backend/docs/**'
+      - 'files_for_readme/ARCHITECTURE_IN_DETAILS.md'
+      - 'backend/tests/load/README.md'
+      - 'mkdocs.yml'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'backend/docs/**'
+      - 'files_for_readme/ARCHITECTURE_IN_DETAILS.md'
+      - 'backend/tests/load/README.md'
+      - 'mkdocs.yml'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:  # Allow manual trigger
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full history for git info
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Cache pip dependencies
+        uses: actions/cache@v4
+        with:
+          key: mkdocs-${{ hashFiles('mkdocs.yml') }}
+          path: ~/.cache/pip
+          restore-keys: |
+            mkdocs-
+
+      - name: Install MkDocs and dependencies
+        run: |
+          pip install --upgrade pip
+          pip install \
+            mkdocs-material \
+            mkdocs-mermaid2-plugin \
+            pymdown-extensions
+
+      - name: Prepare documentation structure
+        run: |
+          # Create directory structure for docs
+          mkdir -p docs/architecture
+          mkdir -p docs/reference
+          mkdir -p docs/components/sse
+          mkdir -p docs/components/workers
+          mkdir -p docs/operations
+          mkdir -p docs/security
+          mkdir -p docs/testing
+          mkdir -p docs/stylesheets
+          mkdir -p docs/assets/images
+
+          # Copy images and assets
+          cp files_for_readme/*.png docs/architecture/
+          cp files_for_readme/*.svg docs/architecture/ 2>/dev/null || true
+          cp files_for_readme/logo.png docs/assets/images/
+
+          # Copy architecture docs
+          cp files_for_readme/ARCHITECTURE_IN_DETAILS.md docs/architecture/overview.md
+          cp backend/docs/services-overview.md docs/architecture/
+          cp backend/docs/kafka-topic-architecture.md docs/architecture/
+          cp backend/docs/lifecycle.md docs/architecture/
+
+          # Copy API reference
+          cp backend/docs/api-reference.md docs/reference/
+
+          # Copy component docs - services overview
+          cp backend/docs/services-overview.md docs/components/
+
+          # Copy SSE docs
+          cp backend/docs/sse-partitioned-architecture.md docs/components/sse/
+          cp backend/docs/execution-sse-flow.md docs/components/sse/
+          cp backend/docs/workers/sse-architecture.md docs/components/sse/
+
+          # Copy worker docs
+          cp backend/docs/workers/pod_monitor.md docs/components/workers/
+          cp backend/docs/workers/result_processor.md docs/components/workers/
+
+          # Copy other component docs
+          cp backend/docs/dead-letter-queue.md docs/components/
+          cp backend/docs/schema-manager.md docs/components/
+
+          # Copy operations docs
+          cp backend/docs/tracing.md docs/operations/
+          cp backend/docs/metrics-contextvars.md docs/operations/
+          cp backend/docs/cpu-time-measurement.md docs/operations/
+          cp backend/docs/notification-types.md docs/operations/
+          cp backend/docs/troubleshooting-result-processor-di-crash.md docs/operations/
+
+          # Copy security docs
+          cp backend/docs/security/policies.md docs/security/
+
+          # Copy testing docs
+          cp backend/tests/load/README.md docs/testing/load-testing.md
+
+          # Create minimal extra.css if not exists
+          if [ ! -f docs/stylesheets/extra.css ]; then
+            echo "/* Custom styles for Integr8sCode docs */" > docs/stylesheets/extra.css
+          fi
+
+      - name: Build documentation
+        run: mkdocs build --strict
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+  deploy:
+    # Only deploy on push to main (not PRs)
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,92 @@
+# MkDocs documentation build output
+site/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.project
+.pydevproject
+.settings/
+
+# Testing
+.coverage
+.pytest_cache/
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+.hypothesis/
+
+# Linting/Type checking
+.mypy_cache/
+.ruff_cache/
+.dmypy.json
+dmypy.json
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Environment files
+.env
+.env.local
+.env.*.local
+*.local.env
+
+# Certificates (generated locally)
+certs/
+*.pem
+*.key
+*.crt
+*.csr
+
+# Kubernetes
+kubeconfig.yaml
+kubeconfig.yml
+
+# Docker
+*.log
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Node (frontend)
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Build outputs
+frontend/public/build/

README.md

@@ -54,7 +54,7 @@ things safe and efficient. You'll get the results back in no time.
 - Backend: `https://127.0.0.1:443/`
   - To check if it works, you can use `curl -k https://127.0.0.1/api/v1/k8s-limits`, should return JSON with current limits
 - Grafana: `http://127.0.0.1:3000` (login - `admin`, pw - `admin123`)
-  
+
 
 You may also find out that k8s doesn't capture metrics (`CPU` and `Memory` params are `null`), it may well be that metrics server
 for k8s is turned off/not enabled. To enable, execute:
@@ -63,9 +63,9 @@ kubectl create -f https://raw.githubusercontent.com/pythianarora/total-practice/
 ```
 
 and test output by writing `kubectl top node` in console, should output sth like:
-``` 
-PS C:\Users\User\Desktop\Integr8sCode> kubectl top node                                                                                                                 
-NAME             CPU(cores)   CPU%   MEMORY(bytes)   MEMORY%   
+```
+PS C:\Users\User\Desktop\Integr8sCode> kubectl top node
+NAME             CPU(cores)   CPU%   MEMORY(bytes)   MEMORY%
 docker-desktop   267m         3%     4732Mi          29%
 ```
 
@@ -77,7 +77,7 @@ docker-desktop   267m         3%     4732Mi          29%
 You can check correctness of start by running a sample test script:
 1. Open website at `https://127.0.0.1:5001/`, go to Editor
 2. In code window, paste following code:
-```python 
+```python
 from typing import TypeGuard
 
 def is_string(value: object) -> TypeGuard[str]:
@@ -97,8 +97,8 @@ example_function("hello")
 example_function([1, 2, 3])
 ```
 
-First, select `>= Python 3.10` and run script, will output: 
-``` 
+First, select `>= Python 3.10` and run script, will output:
+```
 Status: completed
 Execution ID: <some hex number>
 Output:
@@ -107,8 +107,8 @@ Output:
   Something else
 ```
 
-Then, select `< Python 3.10` and do the same: 
-``` 
+Then, select `< Python 3.10` and do the same:
+```
 Status: completed
 Execution ID: <some other hex number>
 Output:
@@ -117,51 +117,25 @@ Output:
           ^
 SyntaxError: invalid syntax
 ```
-This shows that pods with specified python versions are creating and working as expected. Btw, the latter throws error 
+This shows that pods with specified python versions are creating and working as expected. Btw, the latter throws error
 cause `match-case` was introduced first in `Python 3.10`.
 
 </details>
 
 
 ## Architecture Overview
 
-> [!WARNING]
-> Detailed, up-to-date architecture diagrams are in [this file](files_for_readme/ARCHITECTURE_IN_DETAILS.md).
+> [!TIP]
+> Full documentation is available at https://hardmax71.github.io/Integr8sCode/
 
 <img src="./files_for_readme/system_diagram.png" alt="system diagram">
 
 The platform is built on three main pillars:
 
-- **Frontend**: A sleek Svelte app that users interact with.
-- **Backend**: Powered by FastAPI, Python, and MongoDB to handle all the heavy lifting.
-- **Kubernetes Cluster**: Each script runs in its own pod, ensuring isolation and resource control.
-
-## Kubernetes Integration
-
-### Pod Setup
-
-- **Docker Image**:Lightweight Python image with just what we need is used.
-- **Isolation**: Every script gets its own pod for security and reliability.
-- **Cleanup**: Once your script is done, the pod goes away to keep things tidy.
-
-### Resource Management
-
-> [!TIP]
-> By limiting resources, we ensure fair usage and prevent any single script from hogging the system.
-
-- **CPU & Memory Limits**: Each pod has caps to prevent overuse (128 Mi for RAM and 1000m for CPU).
-- **Timeouts**: Scripts can't run forever—they'll stop after a set time (default: 5s).
-- **Disk Space**: Limited to prevent excessive storage use.
-
-> You can find actual limits in dropdown above execution output. 
-
-### Security Considerations
-
-> [!CAUTION]
-> Running user-provided code is risky. We take security seriously to protect both our system and other users.
-
-- **Network Restrictions**: Pods can't make external network calls.
-- **No Privileged Access**: Pods run without elevated permissions.
+- Frontend: A sleek Svelte app that users interact with.
+- Backend: Powered by FastAPI, Python, and MongoDB to handle all the heavy lifting.
+- Kubernetes Cluster: Each script runs in its own pod, ensuring isolation and resource control.
 
-  
+## License
 
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.