diff --git a/architecture.md b/architecture.md
index a97c02d..02daf45 100644
--- a/architecture.md
+++ b/architecture.md
@@ -1,14 +1,67 @@
# Elements
+These are the main elements of this system.
-talk through the pieces
+## Workflow
+This is a [Temporal Workflow](https://docs.temporal.io/workflows) - a durable straightforward description of the process to be executed. For our example see [agent_goal_workflow.py](./workflows/agent_goal_workflow.py).
+Temporal is used to make the process scalable, durable, reliable, secure, and visible.
+
+### Workflow Responsibilities:
+- Orchestrates interactive loop
+- Prompts LLM, Users
+- Keeps record of all interactions ([Signals, Queries, Updates](https://docs.temporal.io/develop/python/message-passing))
+- Executes LLM durably
+- Executes Tools durably
+- Handles failures gracefully
+- Human, LLM and tool interaction history stored for debugging and analysis
+
+## Activities
+These are [Temporal Activities](https://docs.temporal.io/activities). Defined as simple functions, they are auto-retried async/event driven behind the scenes. Activities durably execute Tools and the LLM. See [a sample activity](./activities/tool_activities.py).
+
+## Tools
+Tools define the capabilities of the system. They are simple Python functions (could be in any language).
+They are executed by Temporal Activities. They are “just code” - can connect to any API or system. They also are where the "hard" business logic is: you can validate and retry actions using code you write.
+Failures are handled gracefully by Temporal.
+
+Activities + Tools turn the probabalistic input from the user and LLM into deterministic action.
+
+## Prompts
+Prompts are where the instructions to the LLM & users is. Prompts are made up of initial instructions, goal instructions, and tool instructions.
+See [agent prompts](./prompts/agent_prompt_generators.py) and [goal & tool prompts](./tools/goal_registry.py).
+
+This is where you can add probabalistic business logic, to control process flow, describe what to do, and give instruction and validation for the LLM.
+
+## LLM
+Probabalistic execution: it will _probably_ do what you tell it to do.
+Turns the guidance from the prompts (see [agent prompts](./prompts/agent_prompt_generators.py) and [goal prompts](./tools/goal_registry.py)) into
+You have a choice of providers - see [setup](./setup.md).
+The LLM:
+- Validates user input for tools
+- Drives toward goal selected by user
+- Decides when to execute tools
+- Formats input and interprets output for tools
+- is executed by Temporal Activities
+ - API failures and logical failures are handled transparently
+
+## Interaction
+Interaction is managed with Temporal Signals and Queries. These are durably stored in Workflow History.
+Can be used for analysis and debugging. It's all “just code” so it's easy to add new Signals and Queries.
+Input can be very dynamic, just needs to be serializable.
+
+The workflow executes in a loop: gathering input, validating input, executing tools, managing prompts, and then waiting for input.
+
+
+
+Here's a more detailed example for gathering parameters for tools:
+
+
# Architecture Model
+Now that we have the pieces and what they do, here is a more complete diagram of how the pieces work together:
+
+
-explain elements
-
-tools do determinism
# Adding features
-link to how to LLM interactions/how to change
\ No newline at end of file
+Want to add more tools, See [adding goals and tools](./adding-goals-and-tools.md).
\ No newline at end of file
diff --git a/assets/argument_gathering_cycle.png b/assets/argument_gathering_cycle.png
new file mode 100644
index 0000000..eb97ca8
Binary files /dev/null and b/assets/argument_gathering_cycle.png differ
diff --git a/assets/interaction_loop.png b/assets/interaction_loop.png
new file mode 100644
index 0000000..bbc21d7
Binary files /dev/null and b/assets/interaction_loop.png differ
diff --git a/todo.md b/todo.md
index 87fd312..8e4506e 100644
--- a/todo.md
+++ b/todo.md
@@ -1,18 +1,18 @@
# todo list
-[ ] clean up workflow/make functions
+[x] clean up workflow/make functions
[x] make the debugging confirms optional
[ ] add confirmation env setting to setup guide
[x] document *why* temporal for ai agents - scalability, durability, visibility in the readme
-[ ] fix readme: move setup to its own page, demo to its own page, add the why /|\ section
-[ ] add architecture to readme
+[x] fix readme: move setup to its own page, demo to its own page, add the why /|\ section
+[x] add architecture to readme
- elements of app
- dive into llm interaction
- workflow breakdown - interactive loop
- why temporal
-[ ] setup readme, why readme, architecture readme, what this is in main readme with temporal value props and pictures
+[x] setup readme, why readme, architecture readme, what this is in main readme with temporal value props and pictures
[ ] how to add more scenarios, tools
[ ] create tests