ai cooking
docs are good right? (#297)
authored by
Paul Miller
and committed by
GitHub
b79411f1
eedeed57
+67
+67
docs/data-object-flow.md
+67
docs/data-object-flow.md
···
1
+
# Data Object Flow
2
+
3
+
This document describes the lifecycle of generation data in `internal/recipes`, from query args to regeneration.
4
+
5
+
## 1) `params` is created from query args (generation starts here)
6
+
7
+
Entry point:
8
+
- `GET /recipes?location=...` without `h` query arg
9
+
- Handler: `internal/recipes/server.go` `handleRecipes`
10
+
11
+
Flow:
12
+
1. `handleRecipes` calls `ParseQueryArgs(...)`.
13
+
2. `ParseQueryArgs` (`internal/recipes/params.go`) builds `generatorParams` from URL query args:
14
+
- `location` (required)
15
+
- `date` (optional, defaulted by store timezone/day boundary)
16
+
- `instructions` (optional)
17
+
- `conversation_id` (optional)
18
+
3. `handleRecipes` persists that object with `SaveParams(...)` under `params/<params_hash>`.
19
+
4. This saved `params` object is the start signal for generation. `kickgeneration(...)` is launched immediately after.
20
+
21
+
## 2) `shoppingList` + `recipes` are generated from `params`
22
+
23
+
Async generation path:
24
+
1. `kickgeneration(...)` calls `generator.GenerateRecipes(ctx, params)`.
25
+
2. The generator returns an `ai.ShoppingList` containing `Recipes` (and `ConversationID`).
26
+
3. `SaveShoppingList(...)` persists:
27
+
- `shoppinglist/<params_hash>` -> full `ai.ShoppingList`
28
+
- `recipe/<recipe_hash>` -> each recipe object (with `OriginHash = params_hash`)
29
+
30
+
At this point, `/recipes?h=<params_hash>` can render the generated list.
31
+
32
+
## 3) Optional `selection` state is created to hold user choices
33
+
34
+
After the list exists, a signed-in user can save/dismiss recipes:
35
+
- `POST /recipe/{hash}/save`
36
+
- `POST /recipe/{hash}/dismiss`
37
+
38
+
Both handlers (`handleSaveRecipe`, `handleDismissRecipe`) update `recipeSelection` (`internal/recipes/selection.go`):
39
+
- `SavedHashes []string`
40
+
- `DismissedHashes []string`
41
+
- `UpdatedAt time.Time`
42
+
43
+
Storage key:
44
+
- `recipe_selection/<user_id>/<origin_hash>`
45
+
46
+
This object is optional and exists only when the user starts interacting with save/dismiss actions.
47
+
48
+
## 4) Regeneration creates a new `params` from old `params` + `selection`
49
+
50
+
Regeneration entry:
51
+
- `POST /recipes/{hash}/regenerate`
52
+
- Handler: `handleRegenerate`
53
+
54
+
`handleRegenerate` calls `paramsForAction(...)`, which:
55
+
1. Loads old `params` from `params/<hash>`.
56
+
2. Loads current `shoppingList` from `shoppinglist/<hash>`.
57
+
3. Loads `recipeSelection` for `(user_id, hash)`.
58
+
4. Merges selection state into params (`mergeParamsWithSelection`), applies new instructions, and carries conversation id when needed.
59
+
5. Computes a new hash from the updated params.
60
+
61
+
Then:
62
+
1. New params is saved at `params/<new_hash>`.
63
+
2. `kickgeneration(...)` runs again with that new params.
64
+
65
+
Result:
66
+
- `selection` holds transient decision state for a given origin hash.
67
+
- A new generation cycle begins when a new `params` object is created and saved.