76 lines
3.5 KiB
Markdown
76 lines
3.5 KiB
Markdown
# 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
|
|
```
|
|
|
|
---
|