mirror of
https://github.com/soconnor0919/beenvoice.git
synced 2025-12-11 08:34:43 -05:00
269 lines
7.4 KiB
Markdown
269 lines
7.4 KiB
Markdown
|
|
|
|
# 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**
|
|
```bash
|
|
git clone https://github.com/yourusername/beenvoice.git
|
|
cd beenvoice
|
|
```
|
|
|
|
2. **Install dependencies**
|
|
```bash
|
|
```bash
|
|
bun install
|
|
```
|
|
|
|
3. **Set up environment variables**
|
|
```bash
|
|
cp .env.example .env.local
|
|
```
|
|
|
|
Edit `.env.local` and add your configuration:
|
|
```env
|
|
DATABASE_URL="file:./db.sqlite"
|
|
NEXTAUTH_SECRET="your-secret-key-here"
|
|
NEXTAUTH_URL="http://localhost:3000"
|
|
```
|
|
|
|
4. **Initialize the database**
|
|
```bash
|
|
bun run db:push
|
|
```
|
|
|
|
5. **Start the development server**
|
|
```bash
|
|
bun run dev
|
|
```
|
|
|
|
6. **Open your browser**
|
|
Navigate to [http://localhost:3000](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
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
bun run build
|
|
```
|
|
|
|
2. Start the server:
|
|
```bash
|
|
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:
|
|
|
|
```env
|
|
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](LICENSE) file for details.
|
|
|
|
## 🙏 Acknowledgments
|
|
|
|
- [T3 Stack](https://create.t3.gg/) for the excellent development stack
|
|
- [shadcn/ui](https://ui.shadcn.com/) for beautiful UI components
|
|
- [NextAuth.js](https://next-auth.js.org/) for authentication
|
|
- [Drizzle ORM](https://orm.drizzle.team/) for database management
|
|
|
|
## 📞 Support
|
|
|
|
- **Issues**: [GitHub Issues](https://github.com/yourusername/beenvoice/issues)
|
|
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/beenvoice/discussions)
|
|
- **Email**: support@beenvoice.com
|
|
|
|
---
|
|
|
|
Built for freelancers and small businesses who deserve better invoicing tools.
|