🤖 Tsunagu

-Connecting AI Talent with Opportunity

A modern, full-stack freelance marketplace platform specifically designed for connecting AI experts and developers with clients who need AI/ML services.

Features • Tech Stack • Getting Started • Documentation • Contributing

📖 Overview

Tsunagu (繋ぐ - "to connect") is a purpose-built platform for the AI/ML freelance marketplace, featuring:

🎯 Two User Types: Clients (post AI/ML projects) and Freelancers (submit proposals)
💰 Secure Payments: Milestone-based escrow system with Stripe Connect (50% upfront, 50% on completion)
🔍 Smart Search: Full-text search with PostgreSQL for projects and freelancers
💬 Real-time Messaging: Built-in messaging system for seamless communication
🔔 Notifications: Comprehensive in-app notification system
📊 Project Management: Complete workflow from posting to delivery

Platform Highlights

Payment Model: Fixed-price projects with milestone-based escrow
Platform Fee: 15% (configurable)
Core Flow: Project Posting → Proposal Submission → Hiring → Escrow Payment → Work Delivery → Payout

✨ Features

🔐 Authentication & Authorization

Email/password authentication via Supabase Auth
Role-based access control (Client, Freelancer, Admin)
Email verification and password reset flows
Server-side session management with protected routes

🚀 User Onboarding

Client Onboarding: Profile setup, company information, project goals, budget & timeline preferences
Freelancer Onboarding: Professional profile, skills, portfolio, work experience, hourly rate
Step-by-step guided process with progress tracking

📊 Project Management

Multi-step project posting form with category-based organization
Project statuses: Draft, Open, In Progress, Completed, Cancelled
Project listing and detailed views
Publish/unpublish and close project functionality
Freelancer hiring workflow

💼 Proposal System

Freelancers submit proposals with cover letter, budget, and timeline
Proposal statuses: Submitted, Under Review, Shortlisted, Accepted, Rejected, Withdrawn
View tracking for client engagement
Auto-create conversation on proposal acceptance
Proposal statistics and analytics

🔍 Browse & Search

Advanced Filtering:
- Projects: Category, skills, budget range, full-text search
- Freelancers: Skills, hourly rate, experience, location, full-text search
PostgreSQL Full-Text Search with GIN indexes
Typo tolerance and weighted ranking
Featured projects and top freelancers

💬 Messaging System

One-on-one conversations between clients and freelancers
Unread message tracking
Real-time messaging infrastructure ready
Conversation search by participant name

🔔 Notification System

7 notification categories with 35+ notification types
In-app notifications with customizable preferences
Unread count badges
Mark as read/archive functionality
Click-to-navigate with contextual action URLs

💳 Payment & Escrow (Stripe Connect)

Stripe Connect Integration: Standard accounts for freelancers
Escrow System:
- 50% upfront payment held in platform account
- 50% completion payment after deliverable approval
Platform Fee: 15% automatic deduction
Payment Intents for secure transactions
Automated transfers to freelancer accounts
Webhook handlers for payment events
Transaction history and ledger

👤 User Profiles

Client profiles with company details and project preferences
Freelancer profiles with portfolio, work experience, and skills
Profile visibility and discovery settings

📦 Deliverable Management

Freelancers submit project deliverables
Client review and approval workflow
Revision request system

🛠️ Tech Stack

Frontend

Framework: Next.js 15 (App Router, React 19)
Language: TypeScript (strict mode)
Styling: Tailwind CSS v4
UI Components: Radix UI + shadcn/ui
State Management: TanStack Query (React Query)
Forms: React Hook Form + Zod validation
Internationalization: next-intl

Backend & Database

Database: Supabase (PostgreSQL)
Authentication: Supabase Auth with Row Level Security (RLS)
Real-time: Supabase Realtime (infrastructure ready)
API: tRPC + Next.js API Routes

Payments & Infrastructure

Payments: Stripe Connect for escrow and payouts
Code Quality: Biome for linting and formatting
Package Manager: pnpm

🚀 Getting Started

Prerequisites

Node.js 20+ and pnpm 10+
Supabase Account (Create one free)
Stripe Account (Sign up)

Installation

Clone the repository

git clone https://github.com/yourusername/tsunagu.git
cd tsunagu

Install dependencies
```
pnpm install
```

Set up environment variables

cp .env.example .env

Fill in your environment variables:

# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# Stripe
STRIPE_SECRET_KEY=sk_test_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PLATFORM_FEE_PERCENTAGE=15

# App
NEXT_PUBLIC_URL=http://localhost:3000
NEXT_PUBLIC_API_URL=http://localhost:3000/api

Set up the database

Run the migrations in the supabase/migrations/ folder in order (001-027) in your Supabase SQL Editor, or use the Supabase CLI:
```
npx supabase db push
```
Run the development server
```
pnpm dev
```
Open your browser

Navigate to http://localhost:3000

📁 Project Structure

tsunagu/
├── src/
│   ├── app/                      # Next.js App Router
│   │   ├── [locale]/            # Internationalized routes
│   │   │   ├── (auth)/          # Authentication pages
│   │   │   ├── (public)/        # Public pages (homepage, browse)
│   │   │   └── (protected)/     # Protected pages (dashboard, projects)
│   │   └── api/                 # API routes (Stripe, payments, webhooks)
│   │
│   ├── features/                # Feature-based modules
│   │   ├── auth/               # Authentication
│   │   ├── onboarding/         # User onboarding
│   │   ├── projects/           # Project management
│   │   ├── proposals/          # Proposal system
│   │   ├── browse/             # Browse & search
│   │   ├── messaging/          # Messaging system
│   │   ├── notifications/      # Notification system
│   │   ├── payment/            # Payment UI
│   │   └── profiles/           # User profiles
│   │
│   ├── components/             # Shared UI components
│   │   ├── ui/                 # shadcn/ui components
│   │   ├── layouts/            # Layout components
│   │   └── search/             # Search components
│   │
│   ├── lib/                    # Utility libraries
│   │   ├── supabase/          # Supabase clients (server, client, admin)
│   │   └── stripe/            # Stripe configuration
│   │
│   └── server/                # Server-side code (tRPC)
│
├── supabase/
│   └── migrations/            # Database migrations (001-027)
│
├── public/                    # Static assets
└── email-templates/          # Email templates

📚 Documentation

Core Documentation

CODEBASE_DOCUMENTATION.md - Comprehensive technical documentation (1,600+ lines)
- Complete database schema
- API reference
- Feature implementation details
- RLS policies
- Database functions
STRIPE_CONNECT_SETUP.md - Stripe integration guide (790 lines)
- Setup instructions
- Payment flow diagrams
- Webhook configuration
- Testing guide
SEARCH_IMPROVEMENT_PLAN.md - Search optimization roadmap
notifications.md - Notification types specification

Database Schema

The platform uses 15 core tables:

User Management: users, client_profiles, freelancer_profiles Projects: projects, proposals, project_deliverables Messaging: conversations, conversation_participants, messages Notifications: notifications, notification_preferences Payments: stripe_accounts, payment_intents, transfers, payment_transactions

See CODEBASE_DOCUMENTATION.md for detailed schema documentation.

🧪 Development

Available Scripts

pnpm dev          # Start development server (with Turbopack)
pnpm build        # Build for production
pnpm start        # Start production server
pnpm check        # Run Biome linter
pnpm check:write  # Auto-fix linting issues
pnpm typecheck    # TypeScript type checking

Code Quality

This project uses Biome for fast, unified linting and formatting.

# Check code quality
pnpm check

# Auto-fix issues
pnpm check:write

# Unsafe auto-fix (use with caution)
pnpm check:unsafe

🗺️ Roadmap

✅ Completed Features

Authentication & authorization system
User onboarding flows (client & freelancer)
Project posting and management
Proposal submission and review
Browse and advanced search
Messaging system
Notification system
Stripe Connect integration (backend complete)

🚧 In Progress

Stripe payment UI (frontend)
Real-time message updates
File attachments (projects, messages, deliverables)

📋 Planned

Email notifications (Resend/SendGrid)
Reviews & ratings system
Admin dashboard
Advanced analytics
Mobile responsiveness improvements
Enhanced search with AI-powered matching

🤝 Contributing

We welcome contributions! Here's how you can help:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Contribution Guidelines

Follow the existing code style (enforced by Biome)
Write descriptive commit messages
Update documentation for new features
Add tests where applicable
Ensure pnpm check and pnpm typecheck pass

🐛 Bug Reports & Feature Requests

If you encounter any bugs or have feature suggestions, please open an issue with:

Clear description of the issue/feature
Steps to reproduce (for bugs)
Expected vs actual behavior
Screenshots (if applicable)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with these amazing open-source technologies:

Next.js - The React Framework
Supabase - Open source Firebase alternative
Stripe - Payment infrastructure
Tailwind CSS - Utility-first CSS framework
Radix UI - Unstyled, accessible components
shadcn/ui - Re-usable components

📞 Support

Documentation: CODEBASE_DOCUMENTATION.md
Issues: GitHub Issues
Discussions: GitHub Discussions

⭐ Star this repository if you find it helpful!

Made with ❤️ by the Tsunagu community

Name		Name	Last commit message	Last commit date
Latest commit History 47 Commits
email-templates		email-templates
messages		messages
public		public
src		src
supabase		supabase
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
biome.jsonc		biome.jsonc
components.json		components.json
next.config.js		next.config.js
nextjs-architecture.md		nextjs-architecture.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.js		postcss.config.js
tsconfig.json		tsconfig.json

Devansh-365/tsunagu

Folders and files

Latest commit

History

Repository files navigation