A comprehensive, production-ready CRUD application for managing customers and generating invoices for a small businesses.
Version: 1.24 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, whatever the format they are typed in
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 of service: required, a real date written YYYY-MM-DD
- Price: a number, 0 or more
# 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"]
}The full history is in NODEAPI/VersionLog.md.
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 Project_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 are written to a local graphify-out/ directory, including a persistent graph and report files for documentation-oriented analysis. That directory is gitignored and not committed; regenerate it locally when you need it.
| File | Purpose |
|---|---|
| ./PRD.md | Product requirements: what InvoiceMe does and for whom |
| ./Project_Vision.md | Why the project exists and where it is heading |
| ../Docs/Project_Roadmap.md | Planned improvements and near-term feature roadmap |
| ../Harness_Config/Context/Decisions_Consistency.md | Architecture and engineering decisions (ADRs) |
| ../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
│ ├── tests/ # Jest + Supertest suite; setup in tests/setup/
│ ├── app.js # Express app: middleware, routes, error handling
│ ├── server.js # Bootstrap: env, MongoDB connection, customer and invoice indexes, listen
│ ├── jest.config.js
│ ├── API_DOCUMENTATION.md # API reference
│ ├── VersionLog.md # API change log
│ ├── package.json
│ └── .env.example
├── FRONTEND/
│ ├── src/
│ │ ├── components/ # UI blocks and reusable views
│ │ ├── pages/ # Page-level screens
│ │ ├── config/ # API configuration
│ │ ├── utils/ # Phone number check and display format
│ │ └── App.jsx
│ ├── package.json
│ ├── vite.config.js
│ ├── eslint.config.js
│ ├── postcss.config.js
│ ├── index.html
│ └── public/
├── Docs/
│ ├── README.md # This file
│ ├── PRD.md # Product requirements
│ ├── Project_Vision.md # Vision and direction
│ └── Project_Roadmap.md # Planned work
├── Harness_Config/Context/
│ ├── Architecture_Design.md # Structure and key files
│ ├── DataFlow.md # How a request moves and fails
│ ├── Decisions_Consistency.md # Standing rules (ADRs)
│ └── UI_Guidelines.md # UI authority
├── package.json # Root scripts to run API + frontend together
└── .github/
├── workflows/
└── dependabot.yml
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 20.19+ required (Mongoose 9)
- 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 scripts, which run the API and the frontend together with concurrently.
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:3000
# Tests (no .env or database needed; npm install downloads a MongoDB binary the first time)
npm testcd 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 # in .env.example, not read by the code yet; routes are fixed at /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