# randakamal/kartli architecture

> Architecture diagram of the GitHub repository randakamal/kartli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/randakamal/kartli
- Repository: https://github.com/randakamal/kartli

## Overview

kartli is a shared-kitchen and household app: members create or join a space, manage its shared shopping list and pantry, then record purchases and split costs. The repository also documents receipt scanning and matching, refunds, guest shopping, analytics, invitations, push notifications, themes, and English/German localization. The graph combines sampled page/data-layer references with README-documented capabilities; dashed links mark integrations or wiring not established by the available excerpts.

Main entry points: [`lib/actions/stats.ts`](https://github.com/randakamal/kartli/blob/main/lib/actions/stats.ts) (Spending analytics), [`lib/pantry.ts`](https://github.com/randakamal/kartli/blob/main/lib/pantry.ts) (Pantry inventory), [`lib/kitchen.ts`](https://github.com/randakamal/kartli/blob/main/lib/kitchen.ts) (Kitchen spaces), [`lib/db.ts`](https://github.com/randakamal/kartli/blob/main/lib/db.ts) (PostgreSQL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and spaces"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_account["Accounts<br/>[auth-service.ts]"]
  node_invite["Invitations<br/>[invite.ts]"]
  node_kitchen["Kitchen spaces<br/>[kitchen.ts]"]
  node_kitchen_ui["Kitchen workspace"]
  node_dashboard["Kitchen dashboard<br/>[page.tsx]"]
end

subgraph group_shopping["Shopping and pantry"]
  node_pantry["Pantry inventory<br/>[pantry.ts]"]
  node_pantry_ui["Pantry controls<br/>[PantrySection.tsx]"]
  node_shopping_ui["Shopping list"]
  node_guest["Guest shopping<br/>[GuestView.tsx]"]
end

subgraph group_purchases["Checkout and insights"]
  node_checkout["Purchase checkout<br/>[checkout.ts]"]
  node_receipt["Receipt scanning<br/>[scan-receipt.ts]"]
  node_normalizer["Receipt matching"]
  node_refunds["Refund review"]
  node_analytics["Spending analytics<br/>[stats.ts]"]
end

subgraph group_platform["Shared platform"]
  node_database[("PostgreSQL<br/>[db.ts]")]
  node_gemini["Gemini Vision"]
  node_push["Push notifications<br/>[push.ts]"]
  node_localization["Localization<br/>[context.tsx]"]
end

node_member(("Household member"))

node_member -->|"opens"| node_dashboard
node_dashboard -->|"loads spaces"| node_kitchen
node_dashboard -->|"renders"| node_kitchen_ui
node_member -->|"signs in"| node_auth
node_auth -->|"authenticates"| node_account
node_member -->|"joins by link"| node_invite
node_invite -->|"reads and writes"| node_database
node_kitchen -->|"reads and writes"| node_database
node_kitchen_ui -.->|"manages inventory"| node_pantry
node_member -->|"updates stock"| node_pantry_ui
node_pantry -->|"reads and writes"| node_database
node_pantry -->|"checks admin role"| node_kitchen
node_pantry_ui -->|"adds out-of-stock items"| node_shopping_ui
node_member -->|"shares guest link"| node_guest
node_member -->|"records purchase"| node_checkout
node_checkout -.->|"records checkout"| node_pantry
node_member -->|"scans receipt"| node_receipt
node_receipt -.->|"extracts items"| node_gemini
node_receipt -.->|"matches items"| node_normalizer
node_checkout -.->|"submits for review"| node_refunds
node_member -->|"views spending"| node_analytics
node_analytics -->|"checks membership"| node_kitchen
node_analytics -->|"queries spending"| node_database
node_analytics -->|"normalizes stores"| node_normalizer
node_member -->|"enables alerts"| node_push
node_member -->|"selects language"| node_localization

click node_auth "https://github.com/randakamal/kartli/blob/main/auth.ts"
click node_account "https://github.com/randakamal/kartli/blob/main/lib/auth-service.ts"
click node_invite "https://github.com/randakamal/kartli/blob/main/lib/invite.ts"
click node_kitchen "https://github.com/randakamal/kartli/blob/main/lib/kitchen.ts"
click node_kitchen_ui "https://github.com/randakamal/kartli/blob/main/components/KitchenSpaceView.tsx"
click node_dashboard "https://github.com/randakamal/kartli/blob/main/app/dashboard/page.tsx"
click node_pantry "https://github.com/randakamal/kartli/blob/main/lib/pantry.ts"
click node_pantry_ui "https://github.com/randakamal/kartli/blob/main/components/PantrySection.tsx"
click node_shopping_ui "https://github.com/randakamal/kartli/blob/main/components/ActiveCartSection.tsx"
click node_guest "https://github.com/randakamal/kartli/blob/main/components/kitchen/GuestView.tsx"
click node_checkout "https://github.com/randakamal/kartli/blob/main/app/actions/checkout.ts"
click node_receipt "https://github.com/randakamal/kartli/blob/main/app/actions/scan-receipt.ts"
click node_normalizer "https://github.com/randakamal/kartli/blob/main/lib/receipt-normalizer.ts"
click node_refunds "https://github.com/randakamal/kartli/blob/main/components/AdminRefundsSection.tsx"
click node_analytics "https://github.com/randakamal/kartli/blob/main/lib/actions/stats.ts"
click node_database "https://github.com/randakamal/kartli/blob/main/lib/db.ts"
click node_push "https://github.com/randakamal/kartli/blob/main/lib/push.ts"
click node_localization "https://github.com/randakamal/kartli/blob/main/lib/i18n/context.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_auth,node_account,node_invite,node_kitchen,node_kitchen_ui,node_dashboard toneBlue
class node_pantry,node_pantry_ui,node_shopping_ui,node_guest toneAmber
class node_checkout,node_receipt,node_normalizer,node_refunds,node_analytics toneMint
class node_database,node_gemini,node_push,node_localization toneRose
class node_member toneIndigo
```

## Components

### Identity and spaces

- [Authentication](https://github.com/randakamal/kartli/blob/main/auth.ts): `auth.ts`
- [Accounts](https://github.com/randakamal/kartli/blob/main/lib/auth-service.ts): `lib/auth-service.ts`
- [Invitations](https://github.com/randakamal/kartli/blob/main/lib/invite.ts): `lib/invite.ts`
- [Kitchen spaces](https://github.com/randakamal/kartli/blob/main/lib/kitchen.ts): `lib/kitchen.ts`
- [Kitchen workspace](https://github.com/randakamal/kartli/blob/main/components/KitchenSpaceView.tsx): `components/KitchenSpaceView.tsx`
- [Kitchen dashboard](https://github.com/randakamal/kartli/blob/main/app/dashboard/page.tsx): `app/dashboard/page.tsx`

### Shopping and pantry

- [Pantry inventory](https://github.com/randakamal/kartli/blob/main/lib/pantry.ts): `lib/pantry.ts`
- [Pantry controls](https://github.com/randakamal/kartli/blob/main/components/PantrySection.tsx): `components/PantrySection.tsx`
- [Shopping list](https://github.com/randakamal/kartli/blob/main/components/ActiveCartSection.tsx): `components/ActiveCartSection.tsx`
- [Guest shopping](https://github.com/randakamal/kartli/blob/main/components/kitchen/GuestView.tsx): `components/kitchen/GuestView.tsx`

### Checkout and insights

- [Purchase checkout](https://github.com/randakamal/kartli/blob/main/app/actions/checkout.ts): `app/actions/checkout.ts`
- [Receipt scanning](https://github.com/randakamal/kartli/blob/main/app/actions/scan-receipt.ts): `app/actions/scan-receipt.ts`
- [Receipt matching](https://github.com/randakamal/kartli/blob/main/lib/receipt-normalizer.ts): `lib/receipt-normalizer.ts`
- [Refund review](https://github.com/randakamal/kartli/blob/main/components/AdminRefundsSection.tsx): `components/AdminRefundsSection.tsx`
- [Spending analytics](https://github.com/randakamal/kartli/blob/main/lib/actions/stats.ts): `lib/actions/stats.ts`

### Shared platform

- [PostgreSQL](https://github.com/randakamal/kartli/blob/main/lib/db.ts): `lib/db.ts`
- **Gemini Vision**
- [Push notifications](https://github.com/randakamal/kartli/blob/main/lib/push.ts): `lib/push.ts`
- [Localization](https://github.com/randakamal/kartli/blob/main/lib/i18n/context.tsx): `lib/i18n/context.tsx`

### Other components

- **Household member**

## Connections

- Household member → Kitchen dashboard: opens (evidence: `README.md`)
- Kitchen dashboard → Kitchen spaces: loads spaces (evidence: `app/dashboard/page.tsx`)
- Kitchen dashboard → Kitchen workspace: renders (evidence: `app/dashboard/page.tsx`)
- Household member → Authentication: signs in (evidence: `README.md`)
- Authentication → Accounts: authenticates (evidence: `app/actions/auth.ts`)
- Household member → Invitations: joins by link
- Invitations → PostgreSQL: reads and writes (evidence: `lib/invite.ts`)
- Kitchen spaces → PostgreSQL: reads and writes (evidence: `lib/kitchen.ts`)
- Kitchen workspace → Pantry inventory: manages inventory
- Household member → Pantry controls: updates stock (evidence: `README.md`)
- Pantry inventory → PostgreSQL: reads and writes (evidence: `lib/pantry.ts`)
- Pantry inventory → Kitchen spaces: checks admin role (evidence: `lib/pantry.ts`)
- Pantry controls → Shopping list: adds out-of-stock items (evidence: `README.md`)
- Household member → Guest shopping: shares guest link (evidence: `README.md`)
- Household member → Purchase checkout: records purchase (evidence: `README.md`)
- Purchase checkout → Pantry inventory: records checkout
- Household member → Receipt scanning: scans receipt (evidence: `README.md`)
- Receipt scanning → Gemini Vision: extracts items
- Receipt scanning → Receipt matching: matches items
- Purchase checkout → Refund review: submits for review
- Household member → Spending analytics: views spending (evidence: `README.md`)
- Spending analytics → Kitchen spaces: checks membership (evidence: `lib/actions/stats.ts`)
- Spending analytics → PostgreSQL: queries spending (evidence: `lib/actions/stats.ts`)
- Spending analytics → Receipt matching: normalizes stores (evidence: `lib/actions/stats.ts`)
- Household member → Push notifications: enables alerts (evidence: `README.md`)
- Household member → Localization: selects language (evidence: `README.md`)
