Skip to content

Commit 81984db

Browse files
shadowdevcodeshadowdevcode
authored
Merge pull request #2 from shadowdevcode/codex-docs-refresh-readme
docs: rewrite README and modernize env example
2 parents d963208 + 70d5aa7 commit 81984db

File tree

2 files changed

+214
-39
lines changed

2 files changed

+214
-39
lines changed

‎.env.example‎

Lines changed: 4 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,4 @@
1-
# GEMINI_API_KEY: Required for Gemini AI API calls.
2-
# AI Studio automatically injects this at runtime from user secrets.
3-
# Users configure this via the Secrets panel in the AI Studio UI.
4-
GEMINI_API_KEY="MY_GEMINI_API_KEY"
5-
6-
# APP_URL: The URL where this applet is hosted.
7-
# AI Studio automatically injects this at runtime with the Cloud Run service URL.
8-
# Used for self-referential links, OAuth callbacks, and API endpoints.
9-
APP_URL="MY_APP_URL"
1+
# Gemini API key used by the serverless AI endpoint: POST /api/ai/parse
2+
# Required for local development when testing AI-assisted pantry parsing.
3+
# Set this in your local .env.local and in Vercel project environment variables.
4+
GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

‎README.md‎

Lines changed: 210 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,229 @@
1-
<div align="center">
2-
<img width="1200" height="475" alt="GHBanner" src="https://github.com/user-attachments/assets/0aa67016-6eaf-458a-adb2-6e31a0763ed6" />
3-
</div>
1+
# Rasoi Planner
42

5-
# Run and deploy your AI Studio app
3+
Rasoi Planner is a shared kitchen workflow app for Indian households.
4+
It helps an **Owner** plan meals and manage pantry inventory, while a **Cook** updates stock status in real time (including AI-assisted pantry updates).
65

7-
This contains everything you need to run your app locally.
6+
## Who This Is For (ICP)
87

9-
View your app in AI Studio: https://ai.studio/apps/3900af62-0bf5-496a-a136-d1c8a0c4b8bd
8+
### Primary product users
9+
- **Household Owner**: plans meals, manages pantry, invites/removes cook access, verifies anomalies.
10+
- **Household Cook**: checks daily menu, marks inventory as low/out/in-stock, adds quantity notes, uses AI assistant.
1011

11-
## Run Locally
12+
### Technical stakeholders
13+
- **Contributor**: develops features, fixes bugs, updates rules/tests.
14+
- **QA / Reviewer**: validates role behavior, security rules, and end-to-end journeys.
1215

13-
**Prerequisites:** Node.js
16+
## What Testers Should Validate
1417

18+
| Role | Must Validate |
19+
| --- | --- |
20+
| Product reviewer | Owner and Cook flows are understandable and usable on local app UI |
21+
| QA / E2E reviewer | `npm run e2e` scenarios pass and `test/e2e/artifacts/summary.json` reports `overallPass: true` |
22+
| Security reviewer | `npm run rules:test` passes Firestore access-control constraints |
23+
| Contributor (before merge) | `npm run verify:local` passes (`lint`, `build`, rules tests, E2E) |
24+
25+
## Stack and Runtime Overview
26+
27+
- Frontend: React 19 + Vite + Tailwind
28+
- Backend endpoint: Vercel serverless function at `POST /api/ai/parse`
29+
- Data/Auth: Firebase Auth (Google) + Firestore
30+
- AI: Gemini model via `@google/genai`
31+
- Tests:
32+
- Firestore rules tests via Firebase Emulator
33+
- Browser E2E via Puppeteer + local mocks
34+
35+
## Prerequisites
36+
37+
Install these before local setup:
38+
39+
- Node.js `18+` (LTS recommended)
40+
- npm (comes with Node.js)
41+
- Java `17+` (required by Firestore Emulator used in `rules:test`)
42+
- A Chromium/Chrome browser (for local sign-in popup and E2E)
43+
44+
No global Firebase CLI install is required because `firebase-tools` is in project `devDependencies`.
45+
46+
## Local Setup
1547

1648
1. Install dependencies:
17-
`npm install`
18-
2. Set the `GEMINI_API_KEY` in [.env.local](.env.local) to your Gemini API key
19-
3. Run the app:
20-
`npm run dev`
2149

22-
## Local End-to-End Check Before Vercel
50+
```bash
51+
npm install
52+
```
53+
54+
2. Create local env file from example:
55+
56+
```bash
57+
cp .env.example .env.local
58+
```
59+
60+
3. Set `GEMINI_API_KEY` in `.env.local`.
61+
62+
4. Start the app:
63+
64+
```bash
65+
npm run dev
66+
```
67+
68+
App runs at `http://0.0.0.0:3000` (or `http://localhost:3000`).
69+
70+
## Firebase Auth Local Checklist
71+
72+
Before validating sign-in flows, confirm in Firebase Console:
73+
74+
1. **Authentication -> Sign-in method -> Google** is enabled.
75+
2. **Authentication -> Settings -> Authorized domains** includes `localhost` and `127.0.0.1` (if you use that host).
76+
3. Google popup sign-in works in local browser.
77+
4. Owner can invite/remove cook.
78+
5. Invited cook gets access.
79+
6. Removed cook loses access immediately.
80+
81+
## Command Runbook (Exact Scripts)
82+
83+
All scripts below are defined in `package.json`.
84+
85+
- Start dev server:
86+
87+
```bash
88+
npm run dev
89+
```
90+
91+
- Start E2E-focused dev server config:
92+
93+
```bash
94+
npm run dev:e2e
95+
```
96+
97+
- Type-check:
98+
99+
```bash
100+
npm run lint
101+
```
102+
103+
- Production build:
104+
105+
```bash
106+
npm run build
107+
```
108+
109+
- Preview build output:
110+
111+
```bash
112+
npm run preview
113+
```
114+
115+
- Clean build output:
116+
117+
```bash
118+
npm run clean
119+
```
120+
121+
- Firestore rules tests (emulator-backed):
122+
123+
```bash
124+
npm run rules:test
125+
```
126+
127+
- End-to-end tests:
128+
129+
```bash
130+
npm run e2e
131+
```
132+
133+
- Full local verification before release:
134+
135+
```bash
136+
npm run verify:local
137+
```
138+
139+
## Architecture Snapshot
140+
141+
### Core collections
142+
- `households/{householdId}`
143+
- `households/{householdId}/inventory/{itemId}`
144+
- `households/{householdId}/meals/{YYYY-MM-DD}`
145+
- `households/{householdId}/logs/{logId}`
146+
147+
### Owner vs Cook permissions
148+
Owner permissions:
149+
- create/update/delete inventory
150+
- create/update meals
151+
- invite or remove cook (`cookEmail`)
152+
- read all household data
153+
154+
Cook permissions:
155+
- read household, inventory, meals, logs
156+
- update inventory status and request quantities
157+
- cannot modify meals or delete inventory
158+
159+
These constraints are enforced in `firestore.rules` and validated by `test/rules/run.ts`.
160+
161+
## AI Endpoint Contract
162+
163+
### Endpoint
164+
- `POST /api/ai/parse`
165+
166+
### Request body
167+
168+
```json
169+
{
170+
"input": "tamatar khatam ho gaya",
171+
"inventory": [{ "id": "9", "name": "Tomatoes", "nameHi": "टमाटर" }],
172+
"lang": "hi"
173+
}
174+
```
175+
176+
### Success response (shape)
177+
178+
```json
179+
{
180+
"understood": true,
181+
"message": "optional",
182+
"updates": [{ "itemId": "9", "newStatus": "out", "requestedQuantity": "1kg" }],
183+
"unlistedItems": [{ "name": "Dhania", "status": "low", "category": "Veggies", "requestedQuantity": "2 bunch" }]
184+
}
185+
```
186+
187+
### Failure behavior
188+
- Invalid request body: HTTP `400`
189+
- Missing `GEMINI_API_KEY`: HTTP `503`
190+
- AI/runtime failures: HTTP `500` with safe fallback message
191+
- Client uses safe fallback message if response parsing/validation fails
192+
193+
## Testing and Artifacts
23194

24-
Run the full local verification flow (type-check + production build + Firestore rules tests on emulator + end-to-end tests):
195+
- Firestore rules tests entry: `test/rules/run.ts`
196+
- E2E runner: `test/e2e/run.mjs`
197+
- E2E mock server config: `test/e2e/vite.e2e.config.ts`
198+
- E2E summary output: `test/e2e/artifacts/summary.json`
25199

26-
`npm run verify:local`
200+
## Deployment Notes (Vercel + Firebase)
27201

28-
Firestore rules tests require Java (17 or newer) because the Firestore Emulator runs on Java.
202+
### Vercel
203+
- Ensure rewrites in `vercel.json` are preserved: `/api/*` -> `/api/*` and `/*` -> `/index.html`.
204+
- Set `GEMINI_API_KEY` in Vercel project environment variables.
29205

30-
You can run Firestore rules tests independently:
206+
### Firebase
207+
- Firestore security rules source: `firestore.rules`
208+
- Local emulator config: `firebase.json`
209+
- Confirm production Firebase Auth domain setup before release (Google provider and authorized domains)
31210

32-
`npm run rules:test`
211+
## Troubleshooting
33212

34-
The E2E summary is written to:
213+
### `GEMINI_API_KEY is not configured for the AI parse endpoint`
214+
- Set `GEMINI_API_KEY` in `.env.local` (local) or Vercel environment settings (deploy).
35215

36-
`test/e2e/artifacts/summary.json`
216+
### Firestore rules tests fail with Java/emulator error
217+
- Install Java 17+ and confirm `java -version` resolves correctly in shell.
37218

38-
## Localhost Firebase Auth Checklist
219+
### Google sign-in popup fails locally
220+
- Add `localhost` / `127.0.0.1` to Firebase Auth authorized domains.
221+
- Ensure browser popup blocking is disabled for local app.
39222

40-
Before final deploy validation, confirm these in Firebase Console:
223+
### E2E fails because browser path cannot be resolved
224+
- Install Chrome/Chromium, or set `PUPPETEER_EXECUTABLE_PATH` to a valid browser binary.
41225

42-
1. Authentication → Sign-in method → Google provider is enabled.
43-
2. Authentication → Settings → Authorized domains contains `localhost`.
44-
3. If you use `127.0.0.1` locally, add `127.0.0.1` to Authorized domains as well.
45-
4. Run `npm run dev` and confirm Google popup sign-in works.
46-
5. Validate role permissions:
47-
- Owner can invite/remove cook.
48-
- Invited cook gets access.
49-
- Removed cook loses access immediately.
226+
### AI updates do not change pantry
227+
- Check browser network call to `/api/ai/parse`.
228+
- Confirm request has `input`, `inventory`, and `lang`.
229+
- Confirm response passes schema validation (`understood`, `updates`, `unlistedItems`).

0 commit comments

Comments
 (0)