docs(agile): initialize docs

docs/architecture/api-specification-server-architecture.md

@@ -0,0 +1,75 @@
+# 5. API Specification & Server Architecture
+
+The application will not expose a public REST или GraphQL API. All communication between the frontend and backend will occur internally via **Nuxt 4 Server Routes**. This approach is secure, performant, and perfectly suited for a monolithic fullstack application.
+
+## Server Directory Structure (`server/`)
+
+The server-side logic will be organized as follows:
+
+```plaintext
+server/
+├── api/
+│   ├── cells/
+│   │   ├── index.post.ts       # Create a new Cell
+│   │   └── [id]/
+│   │       ├── index.get.ts    # Get Cell details
+│   │       └── join.post.ts    # Join a Cell (as consumer/executor)
+│   ├── citizens/
+│   │   ├── index.post.ts       # Create a new Citizen (onboarding)
+│   │   └── invite.get.ts       # Generate an invitation link
+│   └── vault/
+│       ├── index.post.ts       # Create a Vault account
+│       ├── login.post.ts       # Login via Vault
+│       └── recover.post.ts     # Initiate/approve social recovery
+├── middleware/
+│   └── auth.ts                 # Middleware to check Citizen authentication
+└── utils/
+    ├── prisma.ts               # Exports a singleton Prisma Client instance
+    └── crypto.ts               # Cryptographic helper functions
+```
+
+## Core API Endpoints (MVP)
+
+| Endpoint | Method | Description | Request Body | Response |
+| :--- | :--- | :--- | :--- | :--- |
+| `/api/citizens` | `POST` | Creates the first Citizen or a new one via invite. | `{ name, publicKey }` | `Citizen` |
+| `/api/citizens/invite` | `GET` | Generates a single-use invitation link. | (none) | `{ inviteUrl }` |
+| `/api/cells` | `POST` | Creates a new "Cell". | `{ commonGood, executors }` | `LedgerEntry` |
+| `/api/cells/[id]` | `GET` | Retrieves the full state of a "Cell". | (none) | `CellState` |
+| `/api/cells/[id]/join` | `POST` | Joins a "Cell" as Executor or Consumer. | `{ role, item? }` | `LedgerEntry` |
+| `/api/cells/[id]/confirm`| `POST` | Confirms payment from a Consumer. | `{ consumerKey }` | `LedgerEntry` |
+
+## Core Workflow: The Cryptographic Signing Process
+
+This sequence diagram illustrates the fundamental process for every action in the system.
+
+```mermaid
+sequenceDiagram
+    participant Browser as Citizen's Browser
+    participant NuxtServer as Nuxt Server / API
+    participant Prisma
+    participant Ledger as The Main Ledger (DB)
+
+    Browser->>Browser: 1. User performs action (e.g., clicks "Create Cell")
+    Browser->>Browser: 2. Prepare `payload` (e.g., { commonGood: "Суп" })
+    Browser->>Browser: 3. Get `previousHash` from last Ledger entry
+    Browser->>Browser: 4. Create `entryHash` from payload + previousHash
+    Browser->>Browser: 5. Sign `entryHash` with private key to get `signature`
+    Browser->>NuxtServer: 6. POST /api/cells (sends payload, publicKey, signature)
+
+    NuxtServer->>NuxtServer: 7. Receive request
+    NuxtServer->>NuxtServer: 8. Validate signature using sender's `publicKey`
+    alt Signature is Invalid
+        NuxtServer-->>Browser: 9a. Return 401 Unauthorized
+    else Signature is Valid
+        NuxtServer->>Prisma: 9b. Get latest `previousHash` from DB
+        NuxtServer->>NuxtServer: 10. Verify client's `previousHash` matches server's
+        NuxtServer->>Prisma: 11. `prisma.ledgerEntry.create(...)`
+        Prisma->>Ledger: 12. INSERT INTO "LedgerEntry"
+        Ledger-->>Prisma: 13. Return new entry
+        Prisma-->>NuxtServer: 14. Return new entry
+        NuxtServer-->>Browser: 15. Return new LedgerEntry (success)
+    end
+```
+
+---