Feat/payroll calculate endpoint

CODE_OF_CONDUCT.md

@@ -0,0 +1,14 @@
+# Code of Conduct
+
+## Our Pledge
+We pledge to make participation in our project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+- Use welcoming and inclusive language.
+- Be respectful of differing viewpoints and experiences.
+- Gracefully accept constructive criticism.
+- Focus on what is best for the community.
+- Show empathy towards other community members.
+
+## Enforcement
+Responsibilities for clarifying standards of acceptable behavior and taking appropriate and fair corrective action in response to any instances of unacceptable behavior lie with the project maintainers.

CONTRIBUTING.md

@@ -0,0 +1,14 @@
+# Contributing to VestRoll
+
+We love your input! We want to make contributing to VestRoll as easy and transparent as possible.
+
+## How to Contribute
+1. Fork the repo and create your branch from `main`.
+2. If you've added code that should be tested, add tests.
+3. If you've changed APIs, update the documentation.
+4. Ensure the test suite passes.
+5. Make sure your code lints.
+6. Issue that pull request!
+
+## License
+By contributing, you agree that your contributions will be licensed under its MIT License.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VestRoll
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,117 +1,156 @@
-# VestRoll: Payroll
+# VestRoll
 
-Stablecoin and fiat Payroll and invoicing platform on Stellar
+<p align="center">
+  <a href="https://github.com/SafeVault/vestroll/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License"></a>
+  <a href="https://stellar.expert/explorer/testnet/"><img src="https://img.shields.io/badge/network-testnet-purple" alt="Testnet"></a>
+  <a href="https://stellar.expert/explorer/public/"><img src="https://img.shields.io/badge/network-mainnet-green" alt="Mainnet"></a>
+</p>
 
----
+<p align="center">
+  <img src="https://img.shields.io/badge/Node.js-20.x-green?style=for-the-badge&logo=node.js" alt="Node.js 20" />
+  <img src="https://img.shields.io/badge/TypeScript-5.x-blue?style=for-the-badge&logo=typescript" alt="TS 5" />
+  <img src="https://img.shields.io/badge/Next.js-15.x-black?style=for-the-badge&logo=next.js" alt="Next.js 15" />
+  <img src="https://img.shields.io/badge/Drizzle-ORM-teal?style=for-the-badge&logo=drizzle" alt="Drizzle" />
+  <img src="https://img.shields.io/badge/Stellar-Wallet-black?style=for-the-badge&logo=stellar" alt="Stellar" />
+</p>
 
-## 🏗️ The 2026 Technology Stack
+**VestRoll** is a professional payroll and invoicing system built on the Stellar network. It enables businesses, contractors, and individuals to manage global payments with automated tax handling using both fiat and stablecoins.
 
-### Core Architecture
+## Features
 
-- **Framework**: [Next.js 15.5](https://nextjs.org/) (App Router & Turbopack)
-- **Library**: [React 19](https://react.dev/)
-- **State**: Redux Toolkit (UI) & Zustand (Store)
+- **Hybrid Payments**: Full support for fiat and stablecoins (USDC) for global settlement.
+- **Payroll Management**: Automated disbursement of payments to large teams in seconds.
+- **Invoice as a Service**: Specialized infrastructure for generating and tracking invoices on Stellar.
+- **Tax Handling**: Integrated tax calculations and reporting for every transaction.
+- **Multi-Account Support**: Tailored experiences for Business, Contractor, and Individual accounts.
 
-### Identity & Privacy (ZK)
+## Tech Stack
 
-- **Auth**: [@stellar/passkey-kit](https://github.com/stellar/passkey-kit) (FaceID/TouchID Biometric Login)
-- **Privacy**: [Stellar Protocol 25 (X-Ray)](https://stellar.org/blog/developers/protocol-25-x-ray) & `circomlib` for ZK-shielded payroll.
-- **Smart Accounts**: [@stellar/smart-account-kit](https://github.com/stellar/smart-account-kit) for automated contract-wallet deployment.
+- **Framework**: [Next.js 15](https://nextjs.org/) (Frontend & API)
+- **Runtime**: Node.js 20 LTS
+- **Database**: PostgreSQL (via Drizzle ORM)
+- **Blockchain**: Stellar Network (SEP-24, Passkey Kit)
+- **State Management**: Redux Toolkit & Zustand
 
-### Finance & Fiat Bridge
+## Quick Start
 
-- **Fiat Providers**: Native integration for **Monnify** and **Flutterwave** (NGN On-ramps).
-- **Stellar Bridge**: [SEP-24](https://stellar.org/developers/stellar-wallet-sdk) via Stellar Wallet SDK for automated NGN-to-USDC settlement.
-- **Gasless UX**: **Launchtube** / Fee-Bumping infrastructure (Zero XLM required for users).
+1. **Clone and Prepare**:
 
----
+   ```bash
+   git clone https://github.com/SafeVault/vestroll.git
+   cd vestroll
+   cp .env.example .env
+   ```
+
+2. **Install Dependencies**:
+
+   ```bash
+   pnpm install
+   ```
+
+3. **Database Setup**:
 
-## 📂 Project Structure
+   ```bash
+   pnpm drizzle-kit push
+   ```
+
+4. **Run in Development**:
+   ```bash
+   pnpm dev
+   ```
+
+## Project Structure
 
-```text
+```
 vestroll/
 ├── src/
-│   ├── api/                # ZK-Circuit logic & Service Orchestration
-│   ├── app/                # Next.js App Router (Invisible Crypto UX)
-│   ├── components/         # Biometric Auth & Shielded UI Components
+│   ├── app/                # Next.js App Router (Pages & API)
+│   ├── components/         # UI Components (Shadcn UI)
 │   ├── server/
-│   │   ├── services/       # Monnify, Flutterwave & Blockchain Services
-│   │   └── db/             # Drizzle Schema (Auth, Org, Fiat, ZK)
-│   └── lib/                # Passkey & Smart Account SDK wrappers
-└── brain/                  # Master Roadmaps & Technical Documentation
+│   │   ├── services/       # Business Logic (Payroll, Tax, Stellar)
+│   │   └── db/             # Drizzle Schema & Migrations
+│   └── lib/                # Shared utilities & SDK wrappers
+├── docs/                   # Comprehensive documentation
+├── public/                 # Static assets
+└── scripts/                # Utility scripts for DB and Swagger
 ```
 
----
+## Documentation
 
-## ✨ Key Features
+Comprehensive documentation is available in the [`/docs`](./docs/) folder:
 
-- **Invisible Onboarding**: Users sign up with Email and Biometrics (Passkeys). No seed phrases, no private keys, no 12-word recovery.
-- **Hybrid Recovery**: A "Best of Both Worlds" security model—Biometric speed for daily use, Email recovery for account resets.
-- **ZK-Shielded Payments**: Payroll amounts are hidden from the public ledger using Zero-Knowledge proofs, providing enterprise-grade confidentiality.
-- **Automated Fiat-Stable Bridge**: Deposits in **Naira (NGN)** are automatically reflected as **USDC** in the Smart Wallet, enabling instant global payouts.
-- **Atomic Batching**: Disburse 100+ payroll entries in a single biometric signature using Soroban atomic transactions.
-- **Invisible Gas**: Transaction fees are sponsored (Launchtube) or paid in USDC, ensuring users never need to hold or know about XLM.
+### Quick Start
 
----
+- **[Main Documentation](./docs/README.md)** - Complete documentation index
 
-## 🎯 Target Audience & Ecosystem Impact
+### Core Documentation
 
-### Who is this for?
+- [Architecture Overview](./docs/architecture/overview.md) - System architecture
+- [Project Overview](./docs/context/project-overview.md) - Vision and goals
+- [User Personas](./docs/context/user-personas.md) - Account types and use cases
 
-- **Global Enterprises**: Companies with distributed teams needing seamless cross-border payroll.
-- **DAO & Web3 Organizations**: Native crypto organizations requiring fiat and stablecoin payroll solutions.
-- **Freelancers & Contractors**: Individuals seeking transparent, instant, and low-fee payments.
+## Use Cases
 
-### Contribution to the Stellar Ecosystem
+### Business Payroll
 
-VestRoll plays a pivotal role in the **Stellar ecosystem** by:
+Manage organizational payroll with ease:
 
-1.  **Driving Real-World Utility**: Moving beyond speculation to practical, high-volume stablecoin use cases (Payroll).
-2.  **Highlighting Efficiency**: Showcasing Stellar's speed and low fees for frequent, small-to-large value transactions.
+1. Deposit funds via fiat or stablecoin.
+2. Automate tax deductions based on jurisdiction.
+3. Disburse payments to contractors and employees instantly.
 
----
+### Contractor Invoicing
 
-## 🚀 Getting Started
+Generate professional invoices and get paid:
 
-### Prerequisites
+1. Create invoices as a service on Stellar.
+2. Receive payments in stablecoins for low-fee global settlement.
+3. Track payment status and tax obligations.
 
-- Node.js 20.x or higher
-- **pnpm** (preferred)
-- **Stellar CLI** (for local Soroban development)
+### Individual Payments
 
-### Installation
+Simple and secure personal payment management:
 
-1. Clone the repository and install dependencies:
-   ```bash
-   pnpm install
-   ```
-2. Configure Environment:
-   Add `STELLAR_RPC_URL` and `LAUNCHTUBE_API_KEY` to your `.env.local`.
-3. **Database Setup & Seeding**:
-   To sync the schema and populate the database with realistic test data:
-   ```bash
-   pnpm drizzle-kit push
-   pnpm db:seed
-   ```
-4. Start development server:
-   ```bash
-   pnpm dev
-   ```
+1. Manage personal balances in fiat or stablecoins.
+2. Secure onboarding with biometric Passkeys.
 
----
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
 
-## 🛡️ Roadmap & Strategy
+## Support
 
-VestRoll development is structured across 4 Strategic Tranches:
+- **Documentation**: [/docs](./docs/)
+- **Issues**: [GitHub Issues](https://github.com/SafeVault/vestroll/issues)
 
-1. **Tranche 1**: Foundation & Biometric Onboarding.
-2. **Tranche 2**: Fiat-Stable Bridge (NGN MVP).
-3. **Tranche 3**: Privacy Shield (Shielded Testnet).
-4. **Tranche 4**: Mainnet Launch & UX Audit.
+## 👥 Maintainers
 
+<table align="center">
+  <tr>
+    <td align="center">
+      <img src="https://github.com/codeze-us.png" alt="codeZe-us" width="150" />
+      <br /><br />
+      <strong>codeZe-us</strong>
+      <br /><br />
+      <a href="https://github.com/codeze-us" target="_blank">GitHub</a>
+    </td>
+  </tr>
+</table>
 
 ---
 
-## 📄 License
+## **Thanks to all the contributors who have made this project possible!**
 
-Commercial - All rights reserved to SafeVault/VestRoll.
+[![Contributors](https://contrib.rocks/image?repo=SafeVault/vestroll)](https://github.com/SafeVault/vestroll/graphs/contributors)
+
+---
+
+<p align="center">
+  <i> Empowering global payroll with Stellar </i>
+</p>
+
+---

SECURITY.md

@@ -0,0 +1,7 @@
+# Security Policy
+
+## Supported Versions
+Only the latest version of VestRoll is supported.
+
+## Reporting a Vulnerability
+Please report security vulnerabilities by opening an issue or contacting the maintainers directly. We aim to respond within 48 hours.

docs/README.md

@@ -0,0 +1,21 @@
+# Documentation Index
+
+Welcome to the VestRoll documentation.
+
+## Sections
+
+### 🏁 [Quick Start](./README.md)
+
+Basic setup and installation.
+
+### 📐 [Architecture](./architecture/overview.md)
+
+System design and technical implementation details.
+
+### 📋 [Project Overview](./context/project-overview.md)
+
+Vision, goals, and roadmap.
+
+### 👥 [User Personas](./context/user-personas.md)
+
+Detailed breakdown of account types (Business, Contractor, Individual).

docs/architecture/overview.md

@@ -0,0 +1,15 @@
+# Architecture Overview
+
+VestRoll is built with a modern, scalable stack focusing on transparency and security.
+
+## System Components
+- **Web App**: Next.js 15 providing a seamless UI and API routes.
+- **Service Layer**: Decoupled business logic for payroll, invoicing, and tax.
+- **Blockchain Layer**: Integration with Stellar for instant global settlement.
+- **Database**: PostgreSQL with Drizzle ORM for type-safe data management.
+
+## Data Flow
+1. User interacts with the Next.js frontend.
+2. API routes call the appropriate service in `src/server/services`.
+3. Services interact with the DB and/or the Stellar network.
+4. Real-time updates are pushed back to the UI.

docs/context/project-overview.md

@@ -0,0 +1,9 @@
+# Project Overview
+
+## Vision
+To provide a seamless, borderless payroll and invoicing experience for the modern global workforce using Stellar.
+
+## Goals
+- **Simplify Global Payments**: Use stablecoins to avoid high fees and slow traditional banking.
+- **Automate Compliance**: Built-in tax handling for various jurisdictions.
+- **Invoicing as a Service**: Provide developers and businesses with an API for Stellar-based invoicing.

docs/context/user-personas.md

@@ -0,0 +1,15 @@
+# User Personas
+
+VestRoll serves three primary user types:
+
+### 1. Business
+- **Needs**: Manage large-scale payroll, track company expenses, handle tax compliance.
+- **Features**: Batch payments, organizational dashboards, detailed reporting.
+
+### 2. Contractor
+- **Needs**: Professional invoicing, fast global payments, easy tax tracking.
+- **Features**: Invoice creation, stablecoin payouts, payment history.
+
+### 3. Individual
+- **Needs**: Receive and send money globally, manage personal balances.
+- **Features**: Simple wallet interface, biometric security, fiat on/off ramps.

drizzle.config.ts

@@ -1,8 +1,7 @@
-import { defineConfig } from "drizzle-kit";
 import fs from "node:fs";
 import path from "node:path";
 
-function getDatabaseUrl() {
+function getDatabaseUrl(): string {
   if (process.env.DATABASE_URL) {
     return process.env.DATABASE_URL;
   }
@@ -22,22 +21,16 @@ function getDatabaseUrl() {
     if (match?.[1]) return match[1].trim();
   }
 
-  return undefined;
-}
-
-const databaseUrl = getDatabaseUrl();
-
-if (!databaseUrl) {
   throw new Error(
     "DATABASE_URL is not set. Add it to .env.local or your shell environment.",
   );
 }
 
-export default defineConfig({
+export default {
   schema: "./src/server/db/schema.ts",
   out: "./drizzle/migrations",
-  dialect: "postgresql",
+  driver: "pg",
   dbCredentials: {
-    url: databaseUrl,
+    connectionString: getDatabaseUrl(),
   },
-});
+};