Add developer documentation site

.github/workflows/backend-lint.yml

@@ -22,19 +22,23 @@ jobs:
       - name: Checkout Repository
         uses: actions/checkout@v4
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
         with:
           node-version: '20'
           cache: 'pnpm'
-          cache-dependency-path: |
-            server/pnpm-lock.yaml
-            client/pnpm-lock.yaml
-
+          cache-dependency-path: server/pnpm-lock.yaml
 
       - name: Install Dependencies
-        run: pnpm install
+        run: pnpm install --frozen-lockfile
 
       - name: Run ESLint
-        run: npm run lint
+        run: pnpm run lint
 
       - name: Check Prettier Formatting
-        run: npm run format
+        run: pnpm run format

.github/workflows/backend-tests.yml

@@ -13,7 +13,7 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
-    
+
     defaults:
       run:
         working-directory: ./server
@@ -22,17 +22,22 @@ jobs:
       - name: Checkout Repository
         uses: actions/checkout@v4
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
         with:
           node-version: '20'
           cache: 'pnpm'
-          cache-dependency-path: |
-            server/pnpm-lock.yaml
-            client/pnpm-lock.yaml
+          cache-dependency-path: server/pnpm-lock.yaml
 
       - name: Install Dependencies
-        run: pnpm install
+        run: pnpm install --frozen-lockfile
 
       - name: Run Backend Tests
-        run: pnpm test -- --ci --coverage --forceExit
+        run: pnpm exec jest --ci --coverage --forceExit
         env:
-          NODE_ENV: test
+          NODE_ENV: test

.github/workflows/docs.yml

@@ -0,0 +1,61 @@
+name: Documentation
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+      - name: Install dependencies
+        working-directory: docs
+        run: npm ci
+      - name: Check Markdown links
+        working-directory: docs
+        run: npm run check:links
+      - name: Build documentation
+        working-directory: docs
+        run: npm run build
+      - uses: actions/configure-pages@v5
+        if: github.event_name != 'pull_request'
+      - uses: actions/upload-pages-artifact@v3
+        if: github.event_name != 'pull_request'
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+.vitepress/cache/
+.vitepress/.temp/
+.vitepress/dist/
+

docs/.markdown-link-check.json

@@ -0,0 +1,9 @@
+{
+  "ignorePatterns": [
+    { "pattern": "^http://localhost" },
+    { "pattern": "^https://localhost" }
+  ],
+  "retryOn429": true,
+  "fallbackRetryDelay": "30s",
+  "aliveStatusCodes": [200, 206]
+}

docs/.vitepress/config.mjs

@@ -0,0 +1,69 @@
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+  title: 'SoroMint',
+  description: 'Developer documentation for the SoroMint platform',
+  base: '/SoroMint/',
+  cleanUrls: true,
+  lastUpdated: true,
+  ignoreDeadLinks: false,
+  themeConfig: {
+    search: { provider: 'local' },
+    nav: [
+      { text: 'Guide', link: '/getting-started' },
+      { text: 'API', link: '/api-documentation' },
+      { text: 'Contracts', link: '/smart-contracts' }
+    ],
+    sidebar: [
+      {
+        text: 'Start here',
+        items: [
+          { text: 'Introduction', link: '/' },
+          { text: 'Getting started', link: '/getting-started' },
+          { text: 'Architecture', link: '/architecture' },
+          { text: 'Environment variables', link: '/env-variables' },
+          { text: 'Freighter wallet', link: '/freighter-setup' }
+        ]
+      },
+      {
+        text: 'Backend and API',
+        items: [
+          { text: 'API reference', link: '/api-documentation' },
+          { text: 'Authentication', link: '/backend-auth' },
+          { text: 'Validation', link: '/api-validation' },
+          { text: 'Pagination', link: '/pagination-guide' },
+          { text: 'Rate limiting', link: '/rate-limiting' },
+          { text: 'Backend testing', link: '/backend-testing' }
+        ]
+      },
+      {
+        text: 'Smart contracts',
+        items: [
+          { text: 'Overview', link: '/smart-contracts' },
+          { text: 'Deploy contracts', link: '/contract-deployment' },
+          { text: 'Contract API', link: '/contract-api' },
+          { text: 'Contract events', link: '/contract-events' },
+          { text: 'Token design', link: '/token-design' },
+          { text: 'Vault system', link: '/vault-system' },
+          { text: 'Streaming payments', link: '/streaming-payments' },
+          { text: 'DAO voting', link: '/dao-voting' },
+          { text: 'Multisig', link: '/multisig-integration' }
+        ]
+      },
+      {
+        text: 'Operations',
+        items: [
+          { text: 'Health checks', link: '/health-checks' },
+          { text: 'Logging', link: '/logging' },
+          { text: 'Backup system', link: '/backup-system' },
+          { text: 'RPC failover', link: '/rpc-failover' },
+          { text: 'Rust testing', link: '/rust-testing-guide' }
+        ]
+      }
+    ],
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/EDOHWARES/SoroMint' }
+    ],
+    footer: { message: 'SoroMint developer documentation' }
+  }
+})

docs/api-documentation.md

@@ -314,4 +314,4 @@ SOROBAN_RPC_URL="https://soroban-test.stellar.org"
 
 ## Support
 
-For issues, feature requests, or contributions, please refer to the [GitHub repository](https://github.com/your-org/soromint).
+For issues, feature requests, or contributions, please refer to the [GitHub repository](https://github.com/EDOHWARES/SoroMint).

docs/architecture.md

@@ -0,0 +1,29 @@
+# Architecture
+
+SoroMint is a full-stack token platform built around a React client, an Express API, MongoDB, Stellar RPC, and a collection of Soroban smart contracts.
+
+## Request flow
+
+1. The client connects to Freighter and submits user actions to the backend API.
+2. Express routes authenticate and validate requests before calling a service.
+3. Services read or persist application state in MongoDB and construct Stellar transactions.
+4. Transactions are simulated and submitted through the configured Soroban RPC endpoint.
+5. Contract events and transaction results are indexed for API and UI consumers.
+
+## Repository map
+
+| Path | Responsibility |
+| --- | --- |
+| `client/` | React and Vite browser application |
+| `server/routes/` | HTTP route definitions |
+| `server/services/` | Business logic and Stellar integration |
+| `server/models/` | MongoDB persistence models |
+| `contracts/` | Soroban contract crates and tests |
+| `docs/` | This VitePress documentation site |
+
+## Cross-cutting concerns
+
+The backend centralizes [authentication](./backend-auth.md), [request validation](./api-validation.md), [rate limiting](./rate-limiting.md), [logging](./logging.md), and [health checks](./health-checks.md). Contract-facing features should document their callable interface in the [contract API](./contract-api.md) and emitted data in [contract events](./contract-events.md).
+
+For feature-specific design details, see [streaming payments](./streaming-payments.md), the [vault system](./vault-system.md), [DAO voting](./dao-voting.md), and [multisig](./multisig-integration.md).
+

docs/contract-api.md

@@ -27,7 +27,7 @@ The AMM layer adds two new contracts:
 - `AmmFactory`: deploys and indexes pools for SoroMint-issued tokens paired with configured XLM/USDC quote-token contracts
 - `AmmPool`: manages constant-product liquidity, LP share accounting, and swap execution for a single token pair
 
-See [docs/amm-factory.md](/home/chinonso-peter/Drips/SoroMint/docs/amm-factory.md) for the full interface summary.
+See [docs/amm-factory.md](./amm-factory.md) for the full interface summary.
 
 ## Metadata Management
 

docs/contract-deployment.md

@@ -0,0 +1,60 @@
+# Deploy smart contracts
+
+This guide targets Stellar testnet. Use a dedicated, minimally funded identity and verify every command before deploying to a public network.
+
+## Install the toolchain
+
+Install Rust, add the WebAssembly target, and install Stellar CLI using the current instructions in the [Stellar developer documentation](https://developers.stellar.org/docs/tools/cli/install-cli).
+
+```bash
+rustup target add wasm32v1-none
+stellar --version
+```
+
+## Configure a testnet identity
+
+```bash
+stellar network use testnet
+stellar keys generate soromint-deployer --network testnet --fund
+stellar keys address soromint-deployer
+```
+
+The identity is stored by Stellar CLI. Do not commit secret keys or recovery phrases.
+
+## Test and build
+
+From the repository root, test the workspace before producing deployable artifacts:
+
+```bash
+cargo test --workspace
+stellar contract build
+```
+
+Optimized WASM reduces storage and execution costs:
+
+```bash
+stellar contract optimize --wasm target/wasm32v1-none/release/<contract_name>.wasm
+```
+
+Replace `<contract_name>` with the artifact emitted by the build. Use the optimized artifact when the command creates one.
+
+## Deploy
+
+```bash
+stellar contract deploy \
+  --wasm target/wasm32v1-none/release/<contract_name>.wasm \
+  --source-account soromint-deployer \
+  --network testnet
+```
+
+Save the returned contract ID in the appropriate deployment environment, not in source code. Initialize the contract with `stellar contract invoke` using the method and arguments documented in the [contract API](./contract-api.md).
+
+## Verify the deployment
+
+1. Query a read-only contract method with `stellar contract invoke`.
+2. Inspect the transaction and contract on [Stellar Expert testnet](https://stellar.expert/explorer/testnet).
+3. Update backend configuration with the deployed contract ID.
+4. Restart the API and exercise its health check and one end-to-end testnet flow.
+
+Production deployments require an explicit release plan, reviewed administrator addresses, secure signing, and a rollback or upgrade strategy.
+

docs/delegated-minting.md

@@ -51,7 +51,7 @@ pub struct MintDelegate {
 - Handles fee sponsorship if configured
 - Emits `dlg_mint` event
 
-**mint_delegate(owner, delegate) -> Option<MintDelegate>**
+**`mint_delegate(owner, delegate) -> Option<MintDelegate>`**
 - Query function to retrieve delegation details
 - Returns None if delegation doesn't exist
 

docs/freighter-setup.md

@@ -0,0 +1,31 @@
+# Freighter wallet setup
+
+Freighter is the browser wallet used to authorize Stellar and Soroban transactions in the SoroMint client.
+
+## Install and create an account
+
+1. Install Freighter from the official [Freighter website](https://www.freighter.app/).
+2. Create a wallet or import an existing recovery phrase.
+3. Store the recovery phrase offline. Never add it to `.env`, commit it, or share it with a contributor.
+4. Open Freighter settings and select **Testnet** for development.
+
+## Fund a testnet account
+
+Copy the public address (it starts with `G`) and fund it using [Stellar testnet faucet](https://developers.stellar.org/docs/tools/quickstart/faucet). Friendbot funds testnet accounts only; testnet balances have no monetary value.
+
+## Connect to SoroMint
+
+1. Start the client and API using the [local setup](./getting-started.md).
+2. Open the client URL in the browser where Freighter is installed.
+3. Select **Connect Wallet** and approve the SoroMint origin.
+4. Check that the address shown by SoroMint matches the active Freighter account and that both use the same network.
+
+Freighter displays transaction details before signing. Confirm the network, contract, method, and amount. Reject any transaction you do not recognize.
+
+## Troubleshooting
+
+- If the wallet is not detected, unlock Freighter and reload the page.
+- If authorization fails, disconnect the site in Freighter and reconnect it.
+- If simulation or submission fails, confirm the client, backend `NETWORK_PASSPHRASE`, and RPC URL all target testnet.
+- If an account is missing, ensure the selected Freighter account was funded on the currently selected network.
+