From 96214e6d0799a6d0cf3736595deb007892bc5ca2 Mon Sep 17 00:00:00 2001
From: Roberto Alsina <roberto.alsina@gmail.com>
Date: Sun, 30 Jun 2024 20:23:53 -0300
Subject: [PATCH] docs

---
 .gitignore                  |  1 -
 DESIGN.md => docs/DESIGN.md |  0
 docs/funkos.md              | 71 +++++++++++++++++++++++++++++++++++++
 3 files changed, 71 insertions(+), 1 deletion(-)
 rename DESIGN.md => docs/DESIGN.md (100%)
 create mode 100644 docs/funkos.md

diff --git a/.gitignore b/.gitignore
index 8de7c79..ff2c02c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,3 @@
-/docs/
 /lib/
 /bin/
 /.shards/
diff --git a/DESIGN.md b/docs/DESIGN.md
similarity index 100%
rename from DESIGN.md
rename to docs/DESIGN.md
diff --git a/docs/funkos.md b/docs/funkos.md
new file mode 100644
index 0000000..8158bfb
--- /dev/null
+++ b/docs/funkos.md
@@ -0,0 +1,71 @@
+# Funkos What, Why, How
+
+A funko is the equivalent of a AWS lambda. It's the unit
+of deployment for FaaSO.
+
+A funko is a folder containing a metadata `funko.yml` file
+and source code in any language supported by a *runtime*
+
+Think of a runtime as a template that gets merged with yout
+funko and produces a full containerized application.
+
+FaaSO can use your funko and its runtime to create a Docker image.
+
+That docker image can be built in a server by the FaaSO proxy or it can be
+built locally just like any docker image.
+
+Then we can start it, either locally or in the server, using the proxy.
+
+```mermaid
+flowchart TD
+subgraph funko_hello
+  A(fa:fa-code Metadata)
+  B(fa:fa-code Code in language X)
+end
+
+R(runtime for X)
+
+C(fa:fa-box Containerized Application)
+D(fa:fa-image Docker Image)
+E(fa:fa-server FaaSO Proxy)
+F(Container Instance Running In Server)
+G(Container Instance Running Locally)
+
+funko_hello --> C -- faaso build --> D
+R --> C
+D --> E -- faaso up --> F
+D -- faaso up -l --> G
+```
+
+How is that application reached? FaaSO will usually run the image
+in a *opinionated* way. All funkos listen in port 3000 in their own
+container instances, and they are all segregated into a network called
+faaso-net.
+
+The faaso-proxy container will automatically proxy all requests so if you access the URL `http://faaso-proxy:8888/funko/hello/foo` that will be
+proxied to `/foo` in the `hello` funko.
+
+This is all done via naming conventions. You can create your own `faaso-whatever` container, add it to the `faaso-net` and faaso will
+happily consider it a funko.
+
+In the same way all funkos are simply docker containers running in that
+network, with names following that convention. There is zero magic
+involved.
+
+```mermaid
+flowchart TD
+subgraph faaso-net
+    faaso-proxy
+    faaso-funko1
+    faaso-funko2
+    faaso-hello
+end
+
+client -- GET /funko/hello/foo --> faaso-proxy
+
+faaso-proxy -- GET /foo --> faaso-hello
+```
+
+The dynamic proxying is achieved by reading the current state of
+Docker and just adapt to it using the naming conventions mentioned
+above.
\ No newline at end of file