etsy-finance-tracker/README.md

# 🎯 Etsy Business Tracker with Advanced Profit Analysis

**Status**: ✅ **LIVE IN PRODUCTION** | **Last Updated**: May 1, 2026

A comprehensive business intelligence platform designed specifically for Etsy sellers to track orders, analyze profit margins, manage expenses, and gain deep insights into business performance with advanced profit analysis capabilities.

## 🚀 **DEPLOYED & READY** - Quick Access

### Production Deployment Options
1. **GitHub Container Registry**: `docker-compose.deploy.yml` - Pre-built images ⚡ Fastest
2. **Local Build**: `docker-compose.simple.yml` - Auto-building 🔧 Most Reliable  
3. **Enhanced Debug**: `docker-compose.deploy-local.yml` - Full logging 🔍 Best for troubleshooting

**🌐 Access URL**: http://localhost:8081 (after deployment)  
**📖 Full Guide**: See `DEPLOYMENT_GUIDE.md` for step-by-step instructions

## ✨ **LIVE FEATURES** - Currently Operational

### 📊 **Advanced Profit Analysis Dashboard** - ✅ LIVE
- **Real-time Profit Tracking**: Monitor profit margins across all products and time periods
- **Cost Breakdown Analysis**: Detailed breakdown of material costs, Etsy fees, shipping expenses
- **Order Drill-Down Analysis**: Product-specific margins with itemized cost analysis
- **Time Range Filtering**: Sophisticated date selectors for monthly, quarterly, yearly analysis
- **Profit Calculation Engine**: Advanced algorithms for accurate margin calculations

### 🏪 **Complete Business Management** - ✅ OPERATIONAL  
- **Order Tracking**: Comprehensive order management with real-time status updates
- **Product Catalog**: Full product database with variants, pricing, inventory tracking
- **Customer Management**: Complete customer data, purchase history, communication logs
- **Expense Management**: Categorized business expense tracking with tax preparation
- **Financial Reporting**: Automated P&L statements and tax-ready financial reports

### 🔄 **Automated Data Processing** - ✅ FUNCTIONAL
- **CSV Import**: Bulk import orders and transactions from Etsy statements  
- **PDF Processing**: Extract data from Etsy payment receipts and statements
- **Smart Product Matching**: AI-powered matching of imported data to product catalog
- **Bulk Operations**: Process hundreds of orders and transactions efficiently

### 🚧 **Coming Soon** - In Active Development
- **Interactive Charts**: Chart.js components for visual profit trends and analytics
- **Product Performance Analysis**: Detailed insights on most/least profitable products  
- **Revenue Forecasting**: Predictive analytics based on historical patterns
- **Seasonal Trend Analysis**: Understanding business cycles and seasonal patterns

## 🛠 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
```

## 🎯 **DEPLOYMENT READY** - Multiple Options Available

### Option 1: Container Interface Deployment (Recommended)
**Perfect for Docker Desktop, Portainer, or similar tools**

1. **Clone Repository**:
   ```bash
   git clone https://github.com/dlawler489/etsy-finance-tracker.git
   cd etsy-finance-tracker
   ```

2. **Choose Your Deployment Method**:
   - `docker-compose.simple.yml` - ⚡ **Best for beginners**
   - `docker-compose.deploy-local.yml` - 🔧 **Enhanced debugging**  
   - `docker-compose.deploy.yml` - 🚀 **Pre-built images (fastest)**

3. **Import & Deploy**:
   - **Docker Desktop**: Compose tab → Import → Select file → Deploy
   - **Portainer**: Stacks → Add stack → Upload file → Deploy
   - **Access**: http://localhost:8081

### Option 2: Command Line Deployment  
```bash
# Quick deployment with pre-built images
docker-compose -f docker-compose.deploy.yml up

# Local build with enhanced debugging
docker-compose -f docker-compose.simple.yml up --build
```

### Option 3: Development Environment
```bash
# For customization and development
npm install
cd client && npm install  
cd ../server && npm install
npm run dev  # Starts both frontend and backend
```

📋 **Validation**: Run `./validate-deployment.sh` to check your environment

## 🏗️ **DEVELOPMENT STATUS & ROADMAP**

### ✅ **Phase 1 - COMPLETED** (April 2026)
- Core profit analysis dashboard with real-time metrics
- Complete business management system (orders, products, customers)
- Advanced data import and processing capabilities  
- Comprehensive deployment infrastructure with multiple options
- Production-ready containerization with CI/CD pipeline

### 🚧 **Phase 2 - IN PROGRESS** (May 2026)
- Interactive Chart.js components for visual analytics
- Advanced product performance analysis with recommendations
- Enhanced profit trending and forecasting capabilities

### 📋 **Phase 3 - PLANNED** (June 2026)  
- AI-powered business insights and recommendations
- Advanced seasonal analysis and inventory optimization
- Mobile app companion for on-the-go business monitoring
   cd etsy-finance-tracker
   ```

2. **Install dependencies**
   ```bash
   cd client && npm install && cd ..
   cd server && npm install && cd ..
   ```

3. **Set up environment variables (optional)**
   ```bash
   cd server
   cp .env.example .env
   # Edit .env if needed for development
   ```

### Development

**Option 1: Run both servers with Docker (recommended)**
```bash
./build-deploy.sh local
```

**Option 2: Run development servers separately**
```bash
npm run dev
```

**Option 2: Run servers separately**

Start the backend server:
```bash
npm run server:dev
# Server runs on http://localhost:8080
```

Start the frontend development server:
```bash
npm run client:dev
# Client runs on http://localhost:3000 (or next available port)
```

### Building for Production

```bash
# Build both client and server
npm run build

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

### Running Tests

```bash
npm test
```

## 🔧 Configuration

### Environment Variables (Server)

Create a `.env` file in the `server` directory:

```env
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)

```bash
# 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

```bash
# 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](LICENSE) file for details.

## 🆘 Troubleshooting

### Common Issues

1. **Port already in use**: If you get an EADDRINUSE error, kill the process using the port:
   ```bash
   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:
   ```bash
   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.**