A comprehensive, production-ready CRUD application for managing customers and generating invoices for a small businesses.
Version: 1.0.0 Status: Production-ready MVP Stack: MERN (MongoDB, Express.js, React.js, Node.js) + Tailwind CSS
InvoiceMe is a full-stack business management app for small businesses that need a lightweight way to manage customer records and generate invoice workflows.
Current delivery includes:
- API versioning with
/api/v1/routes - Customer CRUD with validation and duplicate protection
- Invoice creation and lookup with tax-aware business logic
- PDF-ready invoice flow and frontend invoice views
- MongoDB-backed persistence and health checks for runtime validation
- Responsive React UI built with Vite + Tailwind
- Environment-based configuration for local development and deployment
The project is currently in an active MVP / production-ready iteration for small-business workflows. Core backend and frontend capabilities are implemented, and the repository includes automated dependency and security checks alongside the main Node.js workflow.
Customer Management
- View customers with pagination support
- Create customer records with validation
- Edit existing profiles
- Delete records with confirmation flows
- Prevent duplicate phone numbers on create/update
Invoice Management
- Create invoices from customer and service data
- Calculate tax by state
- Maintain invoice history and lookup endpoints
- Generate invoice data ready for export and PDF rendering
- Track invoice numbers to avoid duplicates
User Interface
- Responsive layout for desktop and tablet usage
- Toast notifications and alert dialogs
- Smooth interaction feedback
- Tailwind-driven styling and modern React components
Customer:
- Phone: Valid US format
- Email: Valid email (optional)
- Zip: 5 or 9 digits (optional)
- State: 2-letter code (optional)
Invoice:
- Phone: Valid US format
- Date: ISO format required
- Price: Positive number
# Get all customers
curl http://localhost:3000/api/v1/customers
# Create customer
curl -X POST http://localhost:3000/api/v1/customers \
-H "Content-Type: application/json" \
-d '{
"companyName": "Tech Corp",
"phoneNumber": "(555) 123-4567"
}'Success:
{
"success": true,
"message": "Operation completed",
"data": {},
"pagination": {}
}Error:
{
"success": false,
"message": "Error description",
"statusCode": 400,
"errors": ["Error 1", "Error 2"]
}Released Features:
- API versioning via
/api/v1/ - Centralized error handling and validation middleware
- Environment-based backend configuration
- Customer CRUD with duplicate prevention
- Invoice management and tax-aware calculations
- React frontend for customer and invoice workflows
- Documentation and roadmap structure in the repo
Key Improvements:
- CORS and runtime-health support for local app development
- Backend route organization by resource
- Pagination and validation for customer listing and create flows
- Security and dependency update checks via GitHub workflows
The project roadmap is tracked in ROADMAP.md. Current focus areas include:
- AI-assisted development environment
- In-memory cache for customer list and tax lookups
- MailTo share/email invoice capability
- Optional Redis-backed cache layer for production use
- Potential architecture refactor for greater modularity
Graphify is available as a tool to support documentation and exploration of the codebase. It can help surface relationships between modules, identify documentation hotspots, and provide a structured knowledge map for the project.
Generated outputs for this repository are stored in the graphify-out/ directory, including a persistent graph and report files for documentation-oriented analysis.
| File | Purpose |
|---|---|
| ../README.md | Repository overview and project entry point |
| ./ROADMAP.md | Planned improvements and near-term feature roadmap |
| ../NODEAPI/API_DOCUMENTATION.md | Complete API reference with examples |
The current codebase follows a small full-stack MVC-style layout with separate API and frontend concerns.
InvoiceMe/
├── NODEAPI/
│ ├── controllers/ # Business logic
│ ├── models/ # MongoDB schemas
│ ├── routes/ # Route handlers
│ ├── middlewares/ # Validation and error handling
│ ├── utils/ # Shared helpers and constants
│ ├── server.js # Express app bootstrap
│ ├── package.json
│ └── .env.example
├── FRONTEND/
│ ├── src/
│ │ ├── components/ # UI blocks and reusable views
│ │ ├── pages/ # Page-level screens
│ │ ├── config/ # API configuration
│ │ └── App.jsx
│ ├── package.json
│ ├── vite.config.js
│ └── tailwind.config.js
├── docs/
│ ├── README.md
│ └── ROADMAP.md
├── package.json # Root scripts to run API + frontend together
├── .github/
│ ├── workflows/
│ └── dependabot.yml
├── graphify-out/
All endpoints use versioning: /api/v1/{resource}
Customer Endpoints:
GET /api/v1/customers # List
GET /api/v1/customers/:id # Get one
POST /api/v1/customers # Create
PUT /api/v1/customers/:id # Update
DELETE /api/v1/customers/:id # Delete
Invoice Endpoints:
GET /api/v1/invoices # List
POST /api/v1/invoices # Create
DELETE /api/v1/invoices/:id # Delete
Tax Endpoints:
POST /api/v1/tax/rate # Get state rate
POST /api/v1/tax/calculate # Calculate
- Node.js 18+ recommended
- MongoDB Atlas or local MongoDB instance
- npm
From the repository root, install dependencies and run the app in development mode:
npm install
npm run devThis uses the root workspace scripts to start both the API and frontend together.
cd NODEAPI
npm install
cp .env.example .env
# Edit .env with your MongoDB URL.
# If you do not have MongoDB Atlas, use a local MongoDB instance:
# MONGO_URL=mongodb://127.0.0.1:27017/API-test
npm run dev
# Server runs on http://localhost:3000cd FRONTEND
npm install
npm run dev
# App runs on http://localhost:5173Note: The frontend is a Vite app and should be started with
npm run devornpm startinside theFRONTENDfolder. Avoid launchingindex.htmldirectly because the app relies on Vite's module system.
MONGO_URL=mongodb+srv://...
PORT=3000
NODE_ENV=development
FRONTEND_URL=http://localhost:5173
API_VERSION=v1 (api/v1/)VITE_API_BASE_URL=http://localhost:3000MongoDB connection error:
- Verify MONGO_URL in .env
- Check IP whitelist on MongoDB Atlas
CORS error:
- Verify FRONTEND_URL matches your frontend domain
- Both must be running
- API questions → API_DOCUMENTATION.md