SRS — {{Project / Feature name}}

Цей контент ще не доступний вашою мовою.

One-line tagline: what this system is, in 12 words or fewer.

1. Purpose

Why does this system exist? What problem does it solve, for whom? One short paragraph (3–6 sentences). No marketing language. No solution wording — describe the gap, not the fix.

2. Stakeholders & Personas

Role	Who	Goal	Influence on requirements
Product Owner	…	…	Final FR/NFR sign-off
Primary user (Persona A)	…	”I want to track my spending without opening an app”	Drives UX latency NFRs
Secondary user (Persona B)	…	…	…
Operator	Self-hosting admin	Keep bot running, restore from backup	Drives ops/observability NFRs

Personas — 1 short paragraph each: context, motivation, pain, technical literacy. Avoid stereotypes; describe behavior, not demographics.

3. Scope

In Scope (this version)

Out of Scope (explicitly deferred)

… (deferred to v0.2 — see Roadmap)
… (non-goal — never)

Explicit Out of Scope is what makes a scope statement useful. “Не написано — не точно” — погано; “Не написано і явно виключено” — добре.

4. Glossary

Term	Definition
Account	A logical wallet (cash / card / deposit) belonging to a user.
Transaction	A single movement of money: expense, income, or transfer.
Ledger	Append-only store of double-entry transfers.
…	…

5. Domain Model

5.1 Entities (overview)

Short prose: 4–8 lines describing the core entities and their relationships.

5.2 ERD

5.3 Lifecycle / state diagrams

If any entity has non-trivial states, draw it. Skip otherwise.

6. Functional Requirements

Format: user stories with BDD acceptance criteria. Each story has a stable ID FR-<MODULE>-<NN>. Acceptance criterion has its own ID AC-<FR-ID>-<n>. Every IF criterion has a paired ELSE / error code. Use must / shall consistently — pick one and stick to it.

FR-EXP-01 — Add an expense from a free-text message

As a Persona-A user I want to type “250 кафе” into the bot chat so that my expense is recorded with the right category without opening any UI.

Acceptance criteria:

AC-FR-EXP-01-1 — Given the user is authenticated When they send a message matching ^\s*(\d+([.,]\d{1,2})?)\s+(.+)$ Then the system MUST persist a Transaction of kind expense with the parsed amount in minor units, current timestamp, and category resolved by alias-match (case-insensitive).
AC-FR-EXP-01-2 — Given the user sends a message that does not match the format When the system parses it Then it MUST reply with ERR_PARSE_001 and the example “1500 метро”, and MUST NOT persist anything.
AC-FR-EXP-01-3 — Given no category alias matches the input When the parser resolves the category Then it MUST fall back to the system category other and the reply MUST flag this fallback so the user can correct it.

FR-LDG-01 — Transfer between own accounts

As a user with two accounts I want to record a transfer “1500 з картки на готівку” so that my account balances stay consistent.

Acceptance criteria:

AC-FR-LDG-01-1 — Given a parsed transfer with valid source and destination accounts When the system records it Then it MUST create exactly one ledger entry that debits source and credits destination atomically. Partial-write of one side without the other MUST NOT be observable.
AC-FR-LDG-01-2 — Given source and destination are the same account When the system validates the transfer Then it MUST reject with ERR_LDG_002 and persist nothing.
AC-FR-LDG-01-3 — Given source account would go below min_balance after the transfer When the validation runs Then the system MUST reject with ERR_LDG_003.

Add as many FR sections as needed. Group by module (EXP, LDG, BUD, RPT, AUTH, …).

7. Non-Functional Requirements

Numbers, not adjectives. “Fast” → “P95 ≤ 500ms”. If you can’t measure it, don’t write it.

7.1 Performance

NFR-PERF-01 — P95 latency from inbound Telegram update to bot reply MUST be ≤ 800 ms at MVP load (≤ 5 rps per pod).

7.2 Reliability & Availability

NFR-REL-01 — Ledger writes MUST be atomic across debit+credit; no partially-applied transfers.
NFR-REL-02 — Bot MUST recover within 30 s after PostgreSQL or TigerBeetle restart, without losing inbound updates (Telegram redelivers via long polling).

7.3 Security & Privacy

NFR-SEC-01 — Each user can only read/write their own data; account isolation enforced at query level (every query filtered by user_id).
NFR-SEC-02 — Telegram bot token, DB credentials, TigerBeetle cluster-id MUST come from env / secret store; never committed.
NFR-SEC-03 — No PII or transaction amounts in logs at INFO level.

7.4 Observability

NFR-OBS-01 — Every inbound update gets a request_id correlated through logs, DB queries, and ledger calls.
NFR-OBS-02 — Metrics exported in Prometheus format: bot_messages_total{kind=…}, ledger_transfer_duration_seconds, db_pool_in_use.

7.5 Maintainability / Portability

NFR-MNT-01 — Ledger interface MUST allow swapping the storage backend (TigerBeetle ↔ Postgres double-entry) without changing call sites in domain code.

8. Constraints & Assumptions

Constraints

C-01 — Telegram is the only UI for MVP. No web, no mobile.
C-02 — Self-hosted on a single VPS for MVP-1; no managed services beyond Telegram itself.
C-03 — Python 3.12+, aiogram 3.x.

Assumptions

A-01 — Users tolerate 30-second outages during deploys (not a payment system).
A-02 — TigerBeetle 0.16+ Python client is stable enough for personal-scale traffic.
A-03 — Users self-onboard without admin intervention from MVP-2 onwards.

If an assumption later turns out false → it becomes a Risk in Appendix C.

9. External Interfaces

Interface	Direction	Protocol	Purpose	Notes
Telegram Bot API	in/out	HTTPS long-polling	User messaging	Token in env; rate limits 30 msg/sec/user
PostgreSQL	out	TCP/5432, asyncpg	System of record (users, accounts, categories, txn metadata)	Pool size 10
TigerBeetle	out	TCP/3000, native client	Ledger (atomic double-entry transfers, balances)	Cluster id pinned in env

Each external interface that has a contract gets its own document under docs/contracts/ (one OpenAPI / one client-spec file per integration).

10. Roadmap (post-MVP)

Phase	Scope addition	Trigger to start
MVP-1	Single user (you + partner), Tier-2 features	now
MVP-2	Self-onboarding, multi-tenant isolation, simple recurring transactions	when ≥ 3 external users want in
MVP-3	Multi-currency, FX revaluation, goals, CSV import/export	when MVP-2 stable for 1 month
v1	Paid tier, advanced reports, web companion	later

Appendix A — Architecture Diagrams

A.1 C4 Level 1 (System Context)

A.2 C4 Level 2 (Containers)

PlantUML for precision; embed rendered PNG.

A.3 Sequence — “Add expense”

Mermaid sequence; embed.

Appendix B — Data Dictionary

Concrete column-level spec for each entity. Implementer builds DDL from this.

Entity	Field	Type	Format	Required	Default	Min/Max	Notes
User	id	UUID	uuid-v4	yes	gen_random_uuid()	—	PK
User	telegram_id	bigint	int64	yes	—	—	UK
Transaction	amount_minor	bigint	int64	yes	—	≥ 0	minor units; e.g. kopecks
Transaction	currency	text	ISO 4217	yes	user.default_currency	3 chars
…	…

Appendix C — Risks & Open Questions

Risks

ID	Description	Likelihood	Impact	Mitigation
R-01	TigerBeetle Python client breaking changes pre-1.0	M	M	Wrap behind ledger interface (NFR-MNT-01)
R-02	Telegram rate-limits during burst of imports	L	M	Queue + backoff

Open Questions

ID	Question	Affects	Owner
OQ-01	Multi-currency in MVP-1 or deferred?	Domain model, FR-EXP	PO

Appendix D — Changelog

Version	Date	Change	Author
0.1.0	YYYY-MM-DD	Initial draft	@zipsybok