diff --git a/Readme.md b/Readme.md index 02e1a0d..b304f80 100644 --- a/Readme.md +++ b/Readme.md @@ -1,90 +1,203 @@
StellarSettle Logo - + # StellarSettle Web App - - **Modern web interface for decentralized invoice financing** - - [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) + + **Web interface for decentralized invoice financing and creator-key markets on Stellar** + [![Next.js](https://img.shields.io/badge/Next.js-15-black)](https://nextjs.org) + [![React](https://img.shields.io/badge/React-19-61DAFB)](https://react.dev) [![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/) + [![Stellar](https://img.shields.io/badge/Stellar-testnet-0066CC)](https://stellar.org)
-## ๐Ÿ“‹ Overview +## Table of Contents + +- [Overview](#overview) +- [Tech Stack](#tech-stack) +- [Project Structure](#project-structure) +- [Feature Areas](#feature-areas) + - [Authentication & Wallet](#authentication--wallet) + - [KYC](#kyc) + - [Invoice Marketplace (Sellers & Investors)](#invoice-marketplace-sellers--investors) + - [Creator Keys](#creator-keys) + - [Admin Panel](#admin-panel) + - [Notifications & Activity](#notifications--activity) +- [API Layer](#api-layer) +- [Getting Started](#getting-started) +- [Environment Variables](#environment-variables) +- [Available Scripts](#available-scripts) +- [Testing](#testing) +- [Continuous Integration](#continuous-integration) +- [Contributing](#contributing) +- [License](#license) + +## Overview + +StellarSettle is a Next.js (App Router) frontend built on two related product surfaces: + +1. **Invoice financing marketplace** โ€” sellers publish invoices for funding, investors browse and invest, funded invoices are tracked through settlement and payout, all gated behind a KYC flow. +2. **Creator Keys** โ€” a tokenized creator-economy layer: buyable/burnable "keys" per creator with governance voting, vesting schedules, whitelisting, dividend distribution, and admin-controlled trading pauses/timelocks. + +Both surfaces share a wallet-based auth layer (Stellar via Freighter), a common API client (`lib/api/index.ts`), and an admin panel that reviews invoices, manages settlements, and controls key trading. + +> Note: this Readme was rewritten from the actual current codebase (routes, `lib/api` exports, `package.json` scripts) rather than the project's original template copy, which described only the invoice-marketplace half and referenced scripts/tooling (Playwright e2e, a11y tests, Docker, Vercel CLI steps) that aren't present in this repo. See [Getting Started](#getting-started) and [Available Scripts](#available-scripts) below for what actually exists today. + +## Tech Stack + +| Concern | Library | +|---|---| +| Framework | Next.js 15 (App Router, Turbopack dev server) | +| UI runtime | React 19 | +| Language | TypeScript 5.7 | +| Styling | Tailwind CSS 4 (`@tailwindcss/postcss`) | +| Component primitives | Radix UI + `radix-ui`, styled as shadcn/ui ("New York" style) | +| Icons | lucide-react | +| Data fetching / cache | TanStack React Query 5 | +| HTTP client | axios | +| Forms | React Hook Form + `@hookform/resolvers` | +| Validation | Zod | +| Charts | Recharts | +| Dates | date-fns | +| Toasts | sonner | +| Theming | next-themes | +| Stellar wallet | `@stellar/freighter-api` | +| Stellar SDK | `stellar-sdk` | +| Unit/component testing | Vitest 4 + Testing Library (React, DOM, user-event) + jsdom | +| Lint | ESLint (`eslint-config-next`) | + +## Project Structure -User-friendly web application for StellarSettle featuring: - -- ๐Ÿ“Š Seller dashboard for invoice management -- ๐Ÿ’ผ Investor marketplace for browsing opportunities -- ๐Ÿ” Stellar wallet integration (Freighter, xBull) -- ๐Ÿ“ˆ Real-time analytics and reporting -- ๐Ÿ“ฑ Responsive mobile-first design -- ๐ŸŒ™ Dark mode support - -## ๐Ÿ—๏ธ Architecture ``` app/ -โ”œโ”€โ”€ (auth)/ # Authentication pages -โ”œโ”€โ”€ (dashboard)/ # Protected dashboard pages -โ”‚ โ”œโ”€โ”€ seller/ # Seller views -โ”‚ โ””โ”€โ”€ investor/ # Investor views -โ”œโ”€โ”€ marketplace/ # Public marketplace -โ””โ”€โ”€ api/ # API routes (if needed) +โ”œโ”€โ”€ page.tsx # Landing page โ€” top-investors leaderboard + recently-viewed invoices +โ”œโ”€โ”€ layout.tsx, error.tsx, not-found.tsx, globals.css +โ”œโ”€โ”€ (auth)/ +โ”‚ โ”œโ”€โ”€ connect-wallet/ # Freighter connection step +โ”‚ โ”œโ”€โ”€ login/ +โ”‚ โ””โ”€โ”€ register/ +โ”œโ”€โ”€ (dashboard)/ +โ”‚ โ”œโ”€โ”€ seller/ # Seller dashboard +โ”‚ โ”‚ โ”œโ”€โ”€ edit/[id]/ # Edit a published invoice +โ”‚ โ”‚ โ”œโ”€โ”€ invoices/[id]/edit/ +โ”‚ โ”‚ โ””โ”€โ”€ publish/ # Publish flow + success page +โ”‚ โ””โ”€โ”€ investor/ # Investor dashboard (portfolio) +โ”‚ โ””โ”€โ”€ notifications/ +โ”œโ”€โ”€ admin/ +โ”‚ โ”œโ”€โ”€ invoices/ # Admin invoice queue +โ”‚ โ””โ”€โ”€ review/ # Admin invoice review +โ”œโ”€โ”€ kyc/ +โ”‚ โ”œโ”€โ”€ start/ +โ”‚ โ”œโ”€โ”€ reapply/ +โ”‚ โ””โ”€โ”€ confirmed/ +โ”œโ”€โ”€ keys/[keyId]/ # Creator key detail page +โ”œโ”€โ”€ marketplace/ +โ”‚ โ””โ”€โ”€ [id]/ # Invoice detail +โ”œโ”€โ”€ profile/ +โ””โ”€โ”€ api/ # (currently unused โ€” .gitkeep only; the app calls an external API via lib/api) components/ -โ”œโ”€โ”€ ui/ # Reusable UI components (shadcn) -โ”œโ”€โ”€ dashboard/ # Dashboard-specific components -โ”œโ”€โ”€ invoices/ # Invoice components -โ””โ”€โ”€ wallet/ # Wallet connection components +โ”œโ”€โ”€ ui/ # shadcn/ui primitives: button, card, input, select, dialog(dropdown/popover), badge, skeleton, sonner, switch, textarea, separator, label +โ”œโ”€โ”€ layout/ # Navbar, NotificationBellBadge, GoToMarketplaceButton +โ”œโ”€โ”€ marketplace/ # invoice-card, filter-bar/FilterPanel, countdown-timer, recently-viewed, TopInvestorsLeaderboard +โ”œโ”€โ”€ invoices/ # PublishInvoiceForm, EditInvoiceForm, InvoiceDetail, InvestDialog/InvestmentModal, DocumentUpload/DocumentPreview, FundingProgressBar, InvoiceStatusBadge, SettlementReturnCard, ShareInvoiceButton, ErrorBoundary +โ”œโ”€โ”€ dashboard/ # SellerDashboard, InvestorPortfolio, PositionCard, PayoutHistoryTable, KycStatusBanner, KycSubmissionForm, NotificationList/Preferences, OnboardingChecklist, UserProfile, WalletActivityFeed, VestingProgressWidget, KeyTransferModal, HoldingActionsMenu +โ”œโ”€โ”€ keys/ # BuyKeyPanel, CreatorKeyDetail, CreatorRevenueSection, CreatorVestingSection, GovernanceTab, VoteModal, CreateProposalModal, SupplyCapSection/Settings, WhitelistManager, BurnKeyModal, DistributeDividendsPanel +โ”œโ”€โ”€ admin/ # AdminInvoiceReview(s), AdminSettlements, AuditLogViewer, TimelockProposalsPanel, TradingControlsPanel +โ”œโ”€โ”€ wallet/ # WalletChip +โ””โ”€โ”€ providers.tsx # App-wide providers (React Query, theming, etc.) + +context/ +โ””โ”€โ”€ AuthContext.tsx # Wallet/session auth state + +hooks/ # One hook per data domain โ€” useAuth, useStellarWallet, useInvoices, useInvestments, + # usePortfolio, useSellerDashboard, useCreatorKeys, useCreatorRevenue, useVesting, + # useWhitelist, useTimelockProposals, useTradingPause, useWalletActivity, + # useNotifications, useNotificationPreferences, useLeaderboard, useRecentlyViewed, + # useCountdown, usePageTitle, usePageLoadPerformanceLog lib/ -โ”œโ”€โ”€ stellar/ # Stellar SDK utilities -โ”œโ”€โ”€ api/ # API client -โ””โ”€โ”€ utils/ # Helper functions - -hooks/ -โ”œโ”€โ”€ useStellar.ts # Stellar wallet hook -โ”œโ”€โ”€ useInvoices.ts # Invoice data hook -โ””โ”€โ”€ useInvestments.ts # Investment data hook +โ”œโ”€โ”€ api/index.ts # Single API client module โ€” every network call + response/request type (see below) +โ”œโ”€โ”€ stellar/index.ts # connectWallet/getNetwork/getAddress/truncateAddress via Freighter +โ”œโ”€โ”€ auth.ts, format.ts, logger.ts, performance-logger.ts, portfolio.ts, recentlyViewed.ts, utils.ts +โ””โ”€โ”€ validation/ # deadline.ts, face-value.ts, investment-amount.ts (Zod schemas) ``` -## ๐Ÿš€ Quick Start +## Feature Areas + +### Authentication & Wallet + +- `(auth)/connect-wallet`, `(auth)/login`, `(auth)/register` handle onboarding. +- `lib/stellar/index.ts` wraps `@stellar/freighter-api`: `connectWallet()`, `getNetwork()`, `getAddress()`, plus a `truncateAddress()` display helper. +- `context/AuthContext.tsx` + `hooks/useAuth.ts` / `useStellarWallet.ts` hold the session/wallet state consumed across the app (e.g. `components/wallet/WalletChip.tsx` in the navbar). + +### KYC + +- `app/kyc/start`, `app/kyc/reapply`, `app/kyc/confirmed` implement the seller KYC flow. +- `submitKyc()` and `fetchSellerKycStatus()` in `lib/api/index.ts`; status is one of the values in `SellerKycStatusValue`, surfaced via `KycStatusBanner`/`KycSubmissionForm`. + +### Invoice Marketplace (Sellers & Investors) + +- **Sellers**: `(dashboard)/seller` โ€” publish (`PublishInvoiceForm`, `publishInvoice()`), edit, and track invoices via `SellerDashboard`/`fetchSellerDashboard()`. +- **Investors**: `/marketplace` browse + filter (`FilterPanel`, `filter-bar`), `/marketplace/[id]` detail + invest (`InvestDialog`/`InvestmentModal` โ†’ `investInInvoice()`), `(dashboard)/investor` portfolio (`InvestorPortfolio`, `fetchPortfolio()`), payout history (`PayoutHistoryTable`, `fetchInvestorPayouts()`). +- Invoices carry `status`: `"open" | "funded" | "settled" | "rejected" | "draft"`, a `yield_percentage`, and support position transfer between investors (`transferInvoicePosition()`). +- Documents attach via `uploadDocumentToIpfs()` (`DocumentUpload`/`DocumentPreview`). +- A leaderboard (`TopInvestorsLeaderboard`, `useLeaderboard`) and a recently-viewed list (`useRecentlyViewed`, backed by `lib/recentlyViewed.ts`) appear on the landing page. + +### Creator Keys + +A parallel tokenized system, per creator: + +- **Buying/burning**: `BuyKeyPanel` โ†’ `buyCreatorKey()`; `BurnKeyModal` โ†’ `burnCreatorKey()`; transfer via `KeyTransferModal` โ†’ `transferCreatorKey()`. +- **Supply**: `KeySupply`, `SupplyCapSection`/`SupplyCapSettings` โ†’ `fetchKeySupply()`, `updateKeySupplyCap()`. +- **Governance**: `GovernanceTab`, `CreateProposalModal`, `VoteModal` โ†’ `fetchKeyProposals()`, `createGovernanceProposal()`, `castGovernanceVote()`. +- **Vesting**: `VestingProgressWidget`, `CreatorVestingSection`, `useVesting` โ†’ `fetchVestingSchedule()`, `claimVestedKeys()`. +- **Whitelisting**: `WhitelistManager`, `useWhitelist` โ†’ `fetchKeyWhitelistStatus()`, `fetchKeyWhitelist()`, `addWhitelistAddress()`, `removeWhitelistAddress()`, `updateWhitelistMode()`. +- **Revenue & dividends**: `CreatorRevenueSection`, `useCreatorRevenue` โ†’ `fetchCreatorRevenue()` (with `MonthlyRevenue` breakdowns); `DistributeDividendsPanel` โ†’ `distributeDividend()`. +- `app/keys/[keyId]` is the public creator-key detail page (`CreatorKeyDetail`, `fetchCreatorKeyDetail()`). + +### Admin Panel + +`app/admin` (invoice queue, review) plus components under `components/admin/`: + +- **Invoice review**: `AdminInvoiceReview(s)` โ†’ `fetchAdminInvoices()`, `approveAdminInvoice()`, `rejectAdminInvoice()`. +- **Settlements**: `AdminSettlements` โ†’ `fetchSettlements()`, `proposeSettlement()`, `approveSettlement()`. +- **Key trading controls**: `TradingControlsPanel`, `useTradingPause` โ†’ `fetchAdminKeyControls()`, `proposeKeyPause()`, `approveKeyPause()` (trading status: `"active" | "pause_pending" | "paused"`). +- **Timelock proposals**: `TimelockProposalsPanel`, `useTimelockProposals` โ†’ `fetchTimelockProposals()`, `executeTimelockProposal()`, `cancelTimelockProposal()`. +- **Audit log**: `AuditLogViewer` โ†’ `fetchAuditLog()`. + +### Notifications & Activity + +- `NotificationList`, `NotificationPreferences`, `NotificationBellBadge`, `useNotifications`/`useNotificationPreferences` โ†’ `fetchNotificationPreferences()`, `updateNotificationPreference()`. Notification events: `"new_invoice" | "funding_milestone" | "settlement"`; channels: `"email" | "in_app"`. +- `WalletActivityFeed`, `useWalletActivity` โ†’ `fetchWalletActivity()` (typed `WalletActivityEvent`/`WalletActivityType`). + +## API Layer + +`lib/api/index.ts` is the single module every hook/component calls into for network access โ€” it has no framework dependency of its own (plain `fetch`/`axios` + typed request/response interfaces) and is the first place to look when tracing a feature end-to-end. It centralizes: invoices, protocol status, notifications, IPFS document upload, portfolio, seller dashboard/KYC, admin invoice + settlement + key-control + timelock + audit endpoints, creator-key detail/governance/whitelist/supply/vesting/revenue, payouts, and wallet activity โ€” see the file directly for exact request/response shapes; every exported function and type is grep-able there in one place (`export async function` / `export interface`). + +## Getting Started ### Prerequisites -- Node.js 18+ -- Stellar wallet browser extension (Freighter recommended) +- Node.js (a version compatible with Next.js 15 / React 19 โ€” Node 18+ is the practical floor) +- A Stellar wallet browser extension for local testing (Freighter) ### Installation + ```bash -# Install dependencies npm install - -# Copy environment variables cp .env.example .env.local - -# Edit environment variables -nano .env.local - -# Start development server +# edit .env.local with real values npm run dev - -# Open http://localhost:3000 +# open http://localhost:3000 ``` -### Install all shadcn/ui components (optional) +`npm run dev` uses Next.js with Turbopack. -The project uses [shadcn/ui](https://ui.shadcn.com) (New York style, Slate theme). A few base components are included. To add the full set (form, dialog, sheet, toast, etc.) run: +## Environment Variables -```bash -# If you see "Lock compromised" or npm cache errors, run first: -npm cache clean --force +From `.env.example`: -# Then install all shadcn components: -npm run shadcn:add -``` - -### Environment Variables ```env # API NEXT_PUBLIC_API_URL=http://localhost:3000/api @@ -103,114 +216,50 @@ NEXT_PUBLIC_ENABLE_ANALYTICS=true NEXT_PUBLIC_ENABLE_NOTIFICATIONS=true ``` -## ๐ŸŽจ Design System - -Built with: -- **UI Components**: shadcn/ui + Radix UI -- **Styling**: TailwindCSS -- **Icons**: Lucide React -- **Charts**: Recharts -- **Forms**: React Hook Form + Zod validation -- **Tables**: TanStack Table - -Color palette: -```css ---primary: #0066CC (Stellar blue) ---secondary: #F8D12F (Stellar yellow) ---accent: #00B4D8 ---background: #FFFFFF / #0A0A0A (dark mode) -``` - -## ๐Ÿ“ฑ Key Features - -### For Sellers -- Upload invoices (PDF, drag-and-drop) -- View invoice status & history -- Track payments in real-time -- Analytics dashboard -- Export reports - -### For Investors -- Browse marketplace with filters -- View invoice risk scores -- One-click investments -- Portfolio tracking -- ROI calculator - -### Shared -- Stellar wallet connection -- Multi-signature support -- Transaction history -- Notifications (email + in-app) -- Mobile responsive - -## ๐Ÿงช Testing -```bash -# Run unit tests -npm test +## Available Scripts -# Run E2E tests (Playwright) -npm run test:e2e +Exactly what's defined in `package.json` โ€” nothing more: -# Run accessibility tests -npm run test:a11y +| Command | Description | +|---|---| +| `npm run dev` | Start the dev server (Turbopack) | +| `npm run build` | Production build | +| `npm start` | Serve the production build | +| `npm run lint` | `next lint` | +| `npm run type-check` | `tsc --noEmit` | +| `npm test` | `vitest run` | +| `npm run shadcn:add` | Installs the full shadcn/ui component set (form, dialog, sheet, toast, table, tabs, tooltip, etc.) beyond the base components already in `components/ui/` โ€” run `npm cache clean --force` first if you hit a "Lock compromised"/npm cache error | -# Generate coverage -npm run test:coverage -``` - -## ๐Ÿš€ Deployment - -### Vercel (Recommended) -```bash -# Install Vercel CLI -npm i -g vercel - -# Deploy -vercel --prod -``` - -### Docker -```bash -# Build image -docker build -t stellarsettle-app . - -# Run container -docker run -p 3000:3000 stellarsettle-app -``` +There is no `test:e2e`, `test:a11y`, `test:coverage`, Docker, or Vercel-CLI script in this repo at present โ€” if you need those workflows, add them rather than assuming they exist. -### Environment Specific -- Development: `npm run dev` -- Staging: `npm run build && npm start` -- Production: Deploy to Vercel/Netlify +## Testing -## ๐Ÿ”’ Security +- **Runner**: Vitest 4, `jsdom` environment, configured in `vitest.config.ts` / `vitest.setup.ts`. +- **Component testing**: `@testing-library/react` + `@testing-library/user-event` + `@testing-library/dom` + `@testing-library/jest-dom` matchers. +- Tests live alongside the code they cover, in `__tests__/` directories: `app/__tests__`, `app/admin/invoices/__tests__`, `app/marketplace/__tests__`, `components/*/__tests__`, `hooks/__tests__`, `lib/__tests__`, `lib/validation/__tests__`, `context/__tests__`. +- Run everything with `npm test`. -- CSP headers configured -- XSS protection via Next.js -- CSRF tokens for sensitive operations -- Wallet signature verification -- Rate limiting on API routes -- Secure cookie settings +## Continuous Integration -## ๐Ÿ“Š Performance +GitHub Actions workflows in `.github/workflows/`: -- Lighthouse score: 95+ -- First Contentful Paint: <1.5s -- Time to Interactive: <3.0s -- Code splitting & lazy loading -- Image optimization (next/image) -- API response caching +- `app-ci.yml` / `ci.yml` โ€” lint, type-check, test, build on PRs. +- `pr-target-check.yml` โ€” enforces the branch-targeting rule below (PRs against `main` are closed automatically). +## Contributing -## ๐Ÿค Contributing +Full detail in [CONTRIBUTING.md](CONTRIBUTING.md); the essentials: -See [CONTRIBUTING.md](../CONTRIBUTING.md) +- **`dev` is the default/active branch.** `main` is production-only. Branch off `dev`, and target `dev` in your PR โ€” a PR opened against `main` is closed automatically. +- Branch naming: `feature/โ€ฆ`, `fix/โ€ฆ`, `docs/โ€ฆ`, `test/โ€ฆ`, `refactor/โ€ฆ`, `chore/โ€ฆ`. +- Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) (`feat(scope): โ€ฆ`, `fix(scope): โ€ฆ`). +- Before opening a PR, run locally (see [DEVELOPMENT.md](DEVELOPMENT.md)): `npm run lint`, `npx tsc --noEmit`, `npm run build`, `npm test`. +- PRs to `dev` need CI green + 1 approval; `dev` โ†’ `main` release PRs need 2 approvals (maintainer-driven; contributors don't need to manage releases). -## ๐Ÿ“„ License +## License -MIT License - see [LICENSE](LICENSE) file for details +No `LICENSE` file is currently present in this repository. Treat licensing as unspecified until the maintainers add one โ€” don't assume MIT (or any other license) from this document alone. --- -Built with โค๏ธ on Stellar +Built on Stellar.