Casa Nostra
Mobile-first web app for transparently managing household expenses between two cohabiting partners. Every expense entered is shared by definition: 50/50 for rent, 60/40 for everything else (the partner with the higher income pays 60%). The app always shows the current balance and lets you settle it in one tap.
It also keeps a shopping list — what's missing at home, by product type, quantity and urgency — with a receipt check that reads a photo of a receipt, ticks off what was bought and highlights what's still missing. The list can be managed from the app, from the AI assistant, or straight from the Telegram group.
For a full guide to the architecture, domain models, and patterns used in the project, see the Developer Wiki (in Italian).
Tech stack
Prerequisites
- Node.js 20 or later
- A Supabase project (free tier works) with access to the admin dashboard
- A Google AI Studio API key for the AI assistant (Gemini)
Project setup
1. Install dependencies
npm install
2. Set up the Supabase database
The database schema (tables, views, RPCs, RLS) is defined in docs/casa_nostra_schema.sql, which is the authoritative source of truth for the applied schema.
- Create a new project on supabase.com.
- Open the project's SQL Editor and run the entire contents of
docs/casa_nostra_schema.sql. (On an existing project, apply only the migrations from docs/migrations/ that it doesn't have yet.)
- The app is designed for exactly two fixed users, created manually (there is no public signup page):
- Go to Authentication → Users → Add user and create the two accounts (email + password).
- Copy the generated UUIDs and insert the two corresponding rows into
public.profiles, following the example in section 9 (BOOTSTRAP dei due profili) at the end of the SQL script.
- Retrieve the project's URL and anon key from Project Settings → API: you'll need them in the next step.
3. Environment variables
Create a .env.local file in the project root (ignored by Git) with the following variables. Each one is documented in detail in docs/wiki/06-configuration.md.
# Supabase — Project Settings → API
NEXT_PUBLIC_SUPABASE_URL=https://<your-project>.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=<your-project-anon-key>
# Google Gemini — AI assistant (route /api/assistant)
GEMINI_API_KEY=<your-google-ai-studio-api-key>
# Optional — default: gemini-flash-lite-latest
GEMINI_MODEL=gemini-flash-lite-latest
# Telegram — optional: group notifications and in-chat assistant
# Full walkthrough: docs/telegram-setup.md
TELEGRAM_BOT_TOKEN=<token-from-botfather>
TELEGRAM_CHAT_ID=<group-chat-id>
TELEGRAM_WEBHOOK_SECRET=<random-string>
TELEGRAM_BOT_USERNAME=<bot-username-without-@>
SUPABASE_SERVICE_ROLE_KEY=<your-project-service-role-key>
NEXT_PUBLIC_SITE_URL=https://<your-app>.vercel.app
| Variable | Required | Scope | Description |
|---|
NEXT_PUBLIC_SUPABASE_URL | Yes | Client + Server | API endpoint of the Supabase project |
NEXT_PUBLIC_SUPABASE_ANON_KEY | Yes | Client + Server | Supabase public "anon" key, enables RLS |
GEMINI_API_KEY | Yes | Server (secret) | Credential for calls to the Google Gemini API |
GEMINI_MODEL | No | Server | Gemini model to use (fallback: gemini-flash-lite-latest) |
TELEGRAM_BOT_TOKEN | For Telegram | Server (secret) | Bot token from @BotFather |
TELEGRAM_CHAT_ID | For Telegram | Server | Id of the group the bot posts to |
TELEGRAM_WEBHOOK_SECRET | For Telegram | Server (secret) | Shared secret verifying that updates really come from Telegram |
TELEGRAM_BOT_USERNAME | Recommended | Server | Bot username without @, used to detect mentions |
TELEGRAM_REPLY_MODE | No | Server | mention (default) or all — when the bot replies in the group |
SUPABASE_SERVICE_ROLE_KEY | For Telegram | Server (secret) | Lets the webhook read/write without a user session (bypasses RLS) |
NEXT_PUBLIC_SITE_URL | Recommended | Client + Server | Public app URL, used for links inside Telegram messages |
Leaving the Telegram variables unset simply keeps the integration off: the app behaves exactly as before.
4. Run in development
npm run dev
Open http://localhost:3000. You'll be redirected to /login: sign in with one of the two accounts created in step 2.
Available scripts
npm run dev # development server (Turbopack)
npm run build # production build
npm run start # start the production build
npm run lint # lint the code (ESLint)
npm run telegram:setup -- chats # list chat ids that messaged the bot
npm run telegram:setup -- set https://<your-app>.vercel.app # register the bot webhook
npm run telegram:setup -- info # inspect webhook status
npm run telegram:setup -- delete # remove the webhook
On Windows, scripts/telegram-setup.ps1 walks through the whole Telegram setup in order — group id, secret, env vars to paste, deploy check, webhook registration — and reports which of the four failure causes it hit if the app isn't answering as it should:
.\scripts\telegram-setup.ps1 -AppUrl https://<your-app>
.\scripts\telegram-setup.ps1 -Info # webhook status and last error
.\scripts\telegram-setup.ps1 -RemoveWebhook
Deployment
The reference deployment target is Vercel:
- Import the repository into Vercel.
- Configure the same environment variables from step 3 under Project Settings → Environment Variables in Vercel.
- Deployment runs automatically on every push to the production branch.
See the Next.js deployment documentation for further details.
Documentation
