Kojori Household Bot

Portfolio-grade Telegram household bot and mini app for shared rent, utilities, purchases, reminders, and lightweight household administration.

The product is built for real group-chat usage: housemates talk in Telegram topics, the bot turns structured messages into deterministic finance records, and the mini app provides a clearer monthly balance view when chat is no longer enough.

What This Repo Shows

This is not a toy Telegram bot repo with a thin webhook and some string parsing. The interesting parts are:

• deterministic money-safe settlement logic with integer minor-unit math
• a hexagonal TypeScript monorepo with explicit domain / application / ports / adapter boundaries
• real operational concerns: idempotency, onboarding flows, localized UX, bot topic setup, reminder scheduling, Terraform-managed infrastructure
• a unified topic processor (gpt-4o-mini) that classifies messages and extracts structured data in a single LLM call
• a product that mixes structured command flows with LLM-assisted parsing while keeping writes deterministic

Current Product Scope

Implemented today:

• Telegram group onboarding with /setup, topic binding, and /unsetup
• topic-based ingestion for purchases, payments, reminders, and anonymous feedback
• DM assistant with household-aware context, payment confirmation flow, and tagged replies in group topics
• deterministic household accounting for rent, utilities, purchases, payments, lifecycle status, and absence policy handling
• mini app authentication, member/admin controls, ledger view, balance dashboard, and household settings
• GCP deployment baseline with Cloud Run, Cloud Scheduler, Secret Manager, Artifact Registry, and Terraform-managed alerting

Still evolving:

• richer mini app finance visualizations
• more advanced setup automation
• deeper member lifecycle and billing policy UX
• broader operational tooling beyond the current alerting baseline

The roadmap and specs are linked below. The README stays intentionally honest: it highlights what is already implemented in code, not everything that is planned.

Architecture

The repo uses a hexagonal structure:

• packages/domain: pure business rules and value objects
• packages/application: use cases and orchestration logic
• packages/ports: external interfaces
• packages/adapters-*: concrete persistence/integration adapters
• apps/bot: grammY delivery layer and bot workflows
• apps/miniapp: SolidJS front-end for richer household admin and finance views

Core invariants:

• no floating-point money math
• store and calculate monetary values in minor units
• keep settlement behavior deterministic
• persist raw parsed purchase text and parser metadata for traceability

Stack

• Bun workspaces
• TypeScript with strict settings and native tsgo typechecking
• grammY for Telegram bot delivery
• SolidJS + Vite for the mini app
• Drizzle for schema and persistence layer
• Terraform for GCP infrastructure
• Oxlint + Oxfmt + Lefthook for local quality gates

Monorepo Layout

apps/
  bot/        Telegram bot delivery, commands, topic ingestion, mini app HTTP handlers
  miniapp/    SolidJS web app for balances, ledger, and household admin

packages/
  domain/         Money, billing periods, IDs, domain rules
  application/    Use cases and orchestration services
  ports/          Interfaces for repositories and integrations
  adapters-db/    Drizzle/Postgres adapter implementations
  db/             Schema, migrations, seed logic
  config/         Shared runtime config parsing
  observability/  Logging and instrumentation helpers

docs/
  roadmap.md
  specs/
  decisions/
  runbooks/

Local Development

Install dependencies:

bun install

Run the main quality gates:

bun run format:check
bun run lint
bun run typecheck
bun run test
bun run build

Run the bot and mini app locally:

bun run dev:bot
bun run dev:miniapp

Database and migration helpers:

bun run db:generate
bun run db:migrate
bun run db:seed

Infrastructure validation:

bun run infra:fmt:check
bun run infra:validate

Container smoke flow:

bun run docker:build
bun run docker:smoke

For a fuller setup walkthrough, see the development setup runbook.

Engineering Notes

Some product choices here are intentional:

• LLMs help interpret messy purchase/payment phrasing, but final writes are still explicit, structured, and confirmable.
• The bot uses a unified topic processor (gpt-4o-mini) that classifies messages and extracts purchase/payment data in a single call. This simplifies the architecture while keeping casual chatter from hitting heavier paths.
• Topic-specific ingestion stays separate from the general assistant so finance actions do not degrade into vague chat behavior.
• Telegram UX is treated as a real product surface: onboarding, confirmation buttons, topic setup, tagged replies, and localization are part of the design, not afterthoughts.
• Infra is versioned alongside the app so deployability, alerts, and runtime configuration are reviewable in the same repo.

Read More

• Roadmap
• Specs guide
• Architecture decisions
• Runbooks

Status

This repository is actively developed and intentionally structured as both:

• a real household-finance product in progress
• a representative engineering sample that shows system design, delivery discipline, and product-minded backend/frontend work in one codebase