Etsy Business Tracker

A comprehensive web application for tracking and managing your Etsy business operations, including products, orders, customers, analytics, and expenses.

🚀 Features

• Dashboard: Real-time overview of business metrics and KPIs
• Product Management: Track product listings, variations, pricing, and inventory
• Order Tracking: Monitor order status, fulfillment, and shipping
• Customer Management: Manage customer data, purchase history, and communication
• Sales Analytics: Revenue tracking, profit margins, and trend analysis
• Expense Tracking: Business expenses, tax deductions, and cost analysis
• Inventory Management: Stock levels, reorder alerts, and supplier tracking
• Financial Reports: P&L statements, tax reports, and business insights

🛠 Tech Stack

Frontend

• React 18 with TypeScript
• Vite for fast development and building
• Tailwind CSS for styling
• Redux Toolkit for state management
• React Router for navigation
• Chart.js for data visualization
• React Hook Form with Zod validation

Backend

• Node.js with Express and TypeScript
• MongoDB with Mongoose ODM
• JWT authentication
• bcryptjs for password hashing
• Helmet for security
• Express Rate Limit for API protection
• Morgan for logging
• Cors for cross-origin requests

📦 Project Structure

etsy-tracker/
├── client/                 # React frontend
│   ├── src/
│   │   ├── components/     # Reusable UI components
│   │   ├── pages/         # Page components
│   │   ├── store/         # Redux store and slices
│   │   ├── utils/         # Utility functions
│   │   └── ...
│   ├── public/
│   └── package.json
├── server/                 # Node.js backend
│   ├── src/
│   │   ├── controllers/   # Route handlers
│   │   ├── models/        # Database models
│   │   ├── routes/        # API routes
│   │   ├── middleware/    # Custom middleware
│   │   └── index.ts       # Server entry point
│   ├── .env.example
│   └── package.json
├── .github/
│   └── copilot-instructions.md
├── package.json           # Root package.json
└── README.md

🚀 Getting Started

Quick Deploy (Recommended)

Option 1: GitHub Container Registry (Fastest)

git clone https://github.com/dlawler489/etsy-finance-tracker.git
cd etsy-finance-tracker
mkdir -p data/{csv,pdf,spreadsheets}
./build-deploy.sh ghcr

Option 2: Local Docker Build

git clone https://github.com/dlawler489/etsy-finance-tracker.git
cd etsy-finance-tracker
./build-deploy.sh local

Both options will start the application at http://localhost:3000

Development Setup

For development and customization:

Prerequisites

• Node.js (v18 or higher)
• npm or yarn
• Docker Desktop (for containerized deployment)

Installation

1. Clone the repository

   git clone https://github.com/dlawler489/etsy-finance-tracker.git
   cd etsy-finance-tracker
   

2. Install dependencies

   cd client && npm install && cd ..
   cd server && npm install && cd ..
   

3. Set up environment variables (optional)

   cd server
   cp .env.example .env
   # Edit .env if needed for development
   

Development

Option 1: Run both servers with Docker (recommended)

./build-deploy.sh local

Option 2: Run development servers separately

npm run dev

Option 2: Run servers separately

Start the backend server:

npm run server:dev
# Server runs on http://localhost:8080

Start the frontend development server:

npm run client:dev
# Client runs on http://localhost:3000 (or next available port)

Building for Production

# Build both client and server
npm run build

# Or build separately
npm run client:build
npm run server:build

Running Tests

npm test

🔧 Configuration

Environment Variables (Server)

Create a .env file in the server directory:

NODE_ENV=development
PORT=8080
CLIENT_URL=http://localhost:3000
MONGODB_URI=mongodb://localhost:27017/etsy-tracker
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
SESSION_SECRET=your-super-secret-session-key-change-this-in-production

Database Setup

The application uses MongoDB to store:

• Products: Product details, variants, pricing, inventory
• Orders: Order information, customer details, status tracking
• Customers: Customer profiles, purchase history
• Expenses: Business expense records
• Users: Authentication and user management

📊 API Endpoints

Authentication

• POST /api/auth/register - User registration
• POST /api/auth/login - User login
• POST /api/auth/logout - User logout
• GET /api/auth/me - Get current user

Products

• GET /api/products - Get all products
• POST /api/products - Create new product
• GET /api/products/:id - Get specific product
• PUT /api/products/:id - Update product
• DELETE /api/products/:id - Delete product

Orders

• GET /api/orders - Get all orders
• POST /api/orders - Create new order
• GET /api/orders/:id - Get specific order
• PUT /api/orders/:id - Update order status

Customers

• GET /api/customers - Get all customers
• POST /api/customers - Create new customer
• GET /api/customers/:id - Get specific customer
• PUT /api/customers/:id - Update customer

Expenses

• GET /api/expenses - Get all expenses
• POST /api/expenses - Create new expense
• PUT /api/expenses/:id - Update expense
• DELETE /api/expenses/:id - Delete expense

Analytics

• GET /api/analytics/dashboard - Get dashboard metrics
• GET /api/analytics/sales - Get sales analytics
• GET /api/analytics/products - Get product performance
• GET /api/analytics/customers - Get customer analytics

🎨 UI/UX

The application features a modern, responsive design built with Tailwind CSS:

• Responsive Design: Works on desktop, tablet, and mobile devices
• Dark/Light Mode: User preference support
• Interactive Charts: Visual analytics and reporting
• Form Validation: Real-time validation with helpful error messages
• Toast Notifications: User feedback for actions

🔒 Security Features

• JWT Authentication: Secure token-based authentication
• Password Hashing: bcrypt for secure password storage
• Rate Limiting: API endpoint protection
• CORS Configuration: Cross-origin request handling
• Input Validation: Server-side validation for all inputs
• Security Headers: Helmet.js for security headers

🚀 Deployment

Using PM2 (Recommended for production)

# Build the application
npm run build

# Install PM2 globally
npm install -g pm2

# Start the server with PM2
cd server
pm2 start dist/index.js --name "etsy-tracker-api"

# Serve the client (using a static file server)
pm2 serve client/dist 3000 --name "etsy-tracker-client"

Using Docker

# Build and run with Docker Compose
docker-compose up --build

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-feature
3. Commit your changes: git commit -am 'Add new feature'
4. Push to the branch: git push origin feature/new-feature
5. Submit a pull request

📝 License

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

🆘 Troubleshooting

Common Issues

1. Port already in use: If you get an EADDRINUSE error, kill the process using the port:

   lsof -ti:8080 | xargs kill -9
   

2. MongoDB connection issues: Ensure MongoDB is running and the connection string is correct in your .env file.

3. Build errors: Clear node_modules and reinstall:

   rm -rf node_modules client/node_modules server/node_modules
   npm run install:all
   

VS Code Integration

This project includes VS Code configuration for:

• Tasks: Pre-configured build and dev tasks
• Debugging: Launch configurations for both client and server
• Extensions: Recommended extensions list
• Settings: Project-specific settings

📞 Support

If you encounter any issues or have questions, please:

1. Check the troubleshooting section above
2. Search existing issues in the repository
3. Create a new issue with detailed information about the problem

---

Built with ❤️ for Etsy sellers who want to grow their business through better data tracking and analysis.