beenvoice/README.md

beenvoice - Invoicing Made Simple

A modern, professional invoicing application built for freelancers and small businesses. beenvoice provides a clean, efficient way to manage clients and create professional invoices with ease.

✨ Features

• 🔐 Secure Authentication - Email/password registration and sign-in with NextAuth.js
• 👥 Client Management - Create, edit, and manage client information
• 📄 Professional Invoices - Generate detailed invoices with line items
• 💰 Flexible Pricing - Set custom rates and calculate totals automatically
• 📱 Responsive Design - Works seamlessly on desktop, tablet, and mobile
• 🎨 Modern UI - Clean, professional interface built with shadcn/ui
• ⚡ Type-Safe - Full TypeScript support with tRPC for API calls
• 💾 Local Database - SQLite database with Drizzle ORM

🚀 Tech Stack

• Frontend: Next.js 15 with App Router
• Backend: tRPC for type-safe API calls
• Database: Drizzle ORM with LibSQL (SQLite)
• Authentication: NextAuth.js with email/password
• UI Components: shadcn/ui with Tailwind CSS
• Styling: Geist font family
• Package Manager: Bun

📦 Installation

Prerequisites

• Node.js 18+ or Bun
• Git

Quick Start

1. Clone the repository

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

2. Install dependencies

   ```bash
   bun install
   

3. Set up environment variables

   cp .env.example .env.local
   

   Edit .env.local and add your configuration:

   DATABASE_URL="file:./db.sqlite"
   NEXTAUTH_SECRET="your-secret-key-here"
   NEXTAUTH_URL="http://localhost:3000"
   

4. Initialize the database

   bun run db:push
   

5. Start the development server

   bun run dev
   

6. Open your browser Navigate to http://localhost:3000

🏗️ Project Structure

beenvoice/
├── src/
│   ├── app/                    # Next.js App Router pages
│   │   ├── api/               # API routes (NextAuth, tRPC)
│   │   ├── auth/              # Authentication pages
│   │   ├── clients/           # Client management pages
│   │   ├── invoices/          # Invoice management pages
│   │   └── _components/       # Page-specific components
│   ├── components/            # Shared UI components
│   ├── server/               # Server-side code
│   │   ├── api/              # tRPC routers
│   │   ├── auth/             # NextAuth configuration
│   │   └── db/               # Database schema and connection
│   ├── styles/               # Global styles
│   └── trpc/                 # tRPC client configuration
├── drizzle/                  # Database migrations
├── public/                   # Static assets
└── docs/                     # Documentation

🎯 Usage

Getting Started

1. Register an Account

   • Visit the sign-up page
   • Enter your name, email, and password
   • Verify your email (if configured)

2. Add Your First Client

   • Navigate to the Clients page
   • Click "Add New Client"
   • Fill in client details (name, email, phone, address)

3. Create an Invoice

   • Go to the Invoices page
   • Click "Create New Invoice"
   • Select a client
   • Add line items with descriptions, dates, hours, and rates
   • Save and generate your invoice

Features Overview

Client Management

• Create and edit client profiles
• Store contact information and addresses
• Search and filter client list
• View client history

Invoice Creation

• Select from existing clients
• Add multiple line items
• Set custom rates per item
• Automatic total calculations
• Professional invoice formatting

User Interface

• Clean, modern design
• Responsive layout
• Intuitive navigation
• Toast notifications for feedback
• Modal dialogs for forms

🔧 Development

Available Scripts

# Development
bun run dev          # Start development server
bun run build        # Build for production
bun run start        # Start production server

# Database
bun run db:push      # Push schema changes to database
bun run db:studio    # Open Drizzle Studio
bun run db:generate  # Generate new migration

# Code Quality
bun run lint         # Run ESLint
bun run format       # Format code with Prettier
bun run type-check   # Run TypeScript type checking

Database Schema

The application uses four main tables:

• users: User accounts and authentication
• clients: Client information and contact details
• invoices: Invoice headers with client relationships
• invoice_items: Individual line items with pricing

API Development

All API endpoints are built with tRPC for type safety:

• Authentication: NextAuth.js integration
• Clients: CRUD operations for client management
• Invoices: Invoice creation and management
• Validation: Zod schemas for input validation

🎨 Customization

Styling

The app uses Tailwind CSS with a custom design system:

• Primary Color: Green (#16a34a)
• Font: Geist for professional typography
• Components: shadcn/ui component library
• Spacing: 4px grid system

Branding

Update the logo and colors in:

• src/components/logo.tsx - Main logo component
• src/styles/globals.css - Color variables
• src/app/layout.tsx - Font configuration

🚀 Deployment

Deployment

You can deploy this application to any platform that supports Next.js (Docker, Coolify, Railway, etc.).

1. Build the application:

bun run build

2. Start the server:

bun start

Other Platforms

The app can be deployed to any platform that supports Next.js:

• Netlify: Use the Next.js build command
• Railway: Connect your GitHub repository
• DigitalOcean App Platform: Deploy with automatic scaling

Environment Variables

Required for production:

DATABASE_URL="your-database-url"
NEXTAUTH_SECRET="your-secret-key"
NEXTAUTH_URL="https://your-domain.com"

🤝 Contributing

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

Development Guidelines

• Follow TypeScript best practices
• Use shadcn/ui components for consistency
• Implement proper error handling
• Add tests for new features
• Follow the existing code style

📄 License

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

🙏 Acknowledgments

• T3 Stack for the excellent development stack
• shadcn/ui for beautiful UI components
• NextAuth.js for authentication
• Drizzle ORM for database management

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: support@beenvoice.com

---

Built for freelancers and small businesses who deserve better invoicing tools.