Next Bill Manager

A modern bill management application for property managers and landlords, built with Next.js 15, TypeScript, and Tailwind CSS.

Features

• Bill Management: Create and track bills with detailed breakdowns
• Tenant Management: Organize tenant information and billing relationships
• Provider Management: Manage utility providers and service accounts
• Dashboard Analytics: Overview with statistics and insights
• Email Integration: Automated email notifications
• Authentication: Secure user authentication
• Responsive Design: Modern UI for all devices

Tech Stack

• Framework: Next.js 15 with App Router
• Language: TypeScript
• Styling: Tailwind CSS
• UI Components: Radix UI + shadcn/ui
• State Management: Jotai
• Authentication: NextAuth.js
• Database: MongoDB
• Email: Gmail API
• Validation: Zod
• Package Manager: pnpm

Quick Start

Prerequisites

• Node.js 18+
• pnpm 10.11.0+
• MongoDB database
• Gmail API credentials (for email features)

Installation

1. Clone the repository

   git clone <repository-url>
   cd next-bill-manager
   

2. Install dependencies

   pnpm install
   

3. Set up environment variables Create a .env.local file:

   # Database
   MONGODB_URI=your_mongodb_connection_string
   MONGODB_DATABASE_NAME=your_database_name
   MONGODB_UTILITY_PROVIDERS=utility_providers
   MONGODB_TENANTS=tenants
   MONGODB_CONSOLIDATED_BILLS=consolidated_bills
   
   # Authentication
   GOOGLE_CLIENT_ID=your_google_client_id
   GOOGLE_CLIENT_SECRET=your_google_client_secret
   NEXTAUTH_URL=http://localhost:3000
   
   # Demo User (optional - for demo mode)
   DEMO_USER_ID=demo-user-123
   DEMO_USER_EMAIL=demo@example.com
   DEMO_USER_NAME=Demo User
   

   Note: After setting up environment variables, run pnpm db:demo:setup to populate demo user data.

4. Run the development server

   pnpm dev
   

Open http://localhost:3000 to see the application.

Project Structure

next-bill-manager/
├── src/
│   ├── app/                   # Next.js app router pages
│   ├── components/            # Shared UI components
│   ├── features/              # Feature-based modules
│   │   ├── bills/             # Bill management
│   │   ├── tenants/           # Tenant management
│   │   ├── providers/         # Provider management
│   │   ├── dashboard/         # Dashboard analytics
│   │   ├── auth/              # Authentication
│   │   └── email/             # Email integration
│   ├── lib/                   # Utility libraries
│   ├── hooks/                 # Shared React hooks
│   ├── states/                # Global state management
│   └── types/                 # Global TypeScript types
├── scripts/                   # Build and database scripts
├── docs/                      # Documentation
└── .github/                   # GitHub Actions workflows

Available Scripts

Development

• pnpm dev - Start development server
• pnpm build - Build for production
• pnpm start - Start production server

Testing

• pnpm test - Run tests
• pnpm test:run - Run tests in CI mode
• pnpm test:coverage - Generate coverage report

Code Quality

• pnpm lint - Run ESLint

Version Management

Releases are handled automatically by Release Please. When a PR is merged to main, a "Release PR" is updated. Merging that PR will tag the version and create a GitHub Release.

Database

• pnpm db:migrate - Run database migrations
• pnpm db:backup - Backup database
• pnpm db:restore - Restore database
• pnpm db:demo:setup - Create demo user data (requires DEMO_USER_ID, DEMO_USER_EMAIL, DEMO_USER_NAME)

Documentation

• Architecture Guide - Technical architecture and code organization
• Contributing Guidelines - Development standards
• API Documentation - Server actions and API reference
• Type Safety Guide - Type safety system
• Versioning Strategy - Version management

Development

This project follows a feature-based architecture with clear dependency rules and comprehensive validation.

Code Organization

• Feature Isolation: Each feature is self-contained
• Barrel Exports: Clean import/export patterns
• Type Safety: Strict TypeScript with runtime validation
• Validation: Automated scripts ensure code quality

Quality Gates

• CI/CD: GitHub Actions with automated deployment
• Linting & Tests: Automated checks on every push
• Production Build: Verified build process

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Follow the Contributing Guidelines
4. Ensure tests pass (pnpm test)
5. Ensure linting passes (pnpm lint)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Quality Requirements

• All tests must pass
• Code must pass linting checks
• Build must complete successfully

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Support

For support and questions:

1. Check the documentation
2. Search existing issues
3. Create a new issue with detailed information

Built with ❤️ using Next.js, TypeScript, and Tailwind CSS