SYSTEM/docs/prd/epic-2-community-expansion-the-first-cell.md

7. Epic 2: Community Expansion & The First "Cell"

Epic Goal: To transform the single-user system into a multi-user "Община" and to implement the core functionality of managing shared finances through "Cells". After this epic, the system will be fully capable of handling the entire lifecycle of a one-time shared expense, from initiation to completion, for a community of two or more "Citizens".

Story 2.1: Citizen Invitation System

As an Initiator, I want to generate a secure, single-use invitation link, so that I can invite new "Citizens" to join my "Община".

Acceptance Criteria:

1. A logged-in "Citizen" (initially, only the Initiator) must have a "Generate Invitation" button on the dashboard.
2. Clicking the button generates a unique, single-use URL.
3. The system must store a record of the generated invitation token to validate it later.
4. The user interface must provide an easy way to copy the generated link.
5. Once an invitation link has been successfully used, it must be invalidated and cannot be used again.

Story 2.2: Onboarding via Invitation

As a new user, I want to be able to join an "Община" using an invitation link, so that I can become a "Citizen" and participate in shared activities.

Acceptance Criteria:

1. Accessing a valid invitation URL must present the new user with the "Citizen" creation screen.
2. The onboarding process must be identical to the "Genesis" flow (Story 1.2), including key generation and profile creation in the "Registry".
3. Upon successful creation, the new "Citizen" is added to the "Община" and can log in.
4. Attempting to access an invalid or already-used invitation URL must show a clear error message.

Story 2.3: "Cell" Creation

As a "Citizen", I want to create a new financial "Cell" for a "Common Good", so that I can initiate a collection of funds for a shared expense.

Acceptance Criteria:

1. The main dashboard must have a "Create Cell" button.
2. The creation form must allow the user to specify the "Common Good" (the purpose, e.g., "Суп").
3. The form must allow the user to define one or more "Executor" roles, including the item to be purchased and its estimated cost (e.g., "Мясо", 100 UAH).
4. Submitting the form must create a new CELL_CREATED transaction in "The Main Ledger".
5. The newly created "Cell" must appear on the main dashboard in an "Open" state.

Story 2.4: Participating in a "Cell"

As a "Citizen", I want to be able to join an existing "Cell" as either an "Executor" or a "Consumer", so that I can take part in the shared expense.

Acceptance Criteria:

1. In the "Cell" detail view, a "Citizen" can choose to become an "Executor" for an unassigned item.
2. Any "Citizen" (including "Executors") can join the "Cell" as a "Consumer".
3. When a "Citizen" joins, the system must re-calculate and display the updated debts for all "Consumers" to all "Executors".
4. Each act of joining (as Executor or Consumer) must be recorded as a distinct, signed transaction in "The Main Ledger".

Story 2.5: Payment Confirmation

As an "Executor", I want to be able to confirm that I have received a payment from a "Consumer", so that their debt is officially cleared in the system.

Acceptance Criteria:

1. In the "Cell" detail view, an "Executor" must see a list of "Consumers" who owe them money.
2. Next to each "Consumer's" name, there must be a "Confirm Payment" button.
3. Clicking the button must create a PAYMENT_CONFIRMED transaction, signed by the "Executor's" private key, which includes the IDs of both the "Consumer" and "Executor".
4. After confirmation, the UI must immediately update to show that the specific debt is cleared.

---