https://github.com/sht/spends
Self-hosted purchase & warranty tracker with spending analytics. Track expenses, monitor warranties, and visualize your spending patterns. Built with FastAPI + Alpine.js
https://github.com/sht/spends
alpinejs expense-manager fastapi personal-finance purchase-tracker self-hosted vitejs warranty-tracker
Last synced: 10 days ago
JSON representation
Self-hosted purchase & warranty tracker with spending analytics. Track expenses, monitor warranties, and visualize your spending patterns. Built with FastAPI + Alpine.js
- Host: GitHub
- URL: https://github.com/sht/spends
- Owner: sht
- License: mit
- Created: 2026-01-30T00:38:17.000Z (5 months ago)
- Default Branch: master
- Last Pushed: 2026-03-19T22:09:49.000Z (3 months ago)
- Last Synced: 2026-06-19T01:37:03.208Z (10 days ago)
- Topics: alpinejs, expense-manager, fastapi, personal-finance, purchase-tracker, self-hosted, vitejs, warranty-tracker
- Language: JavaScript
- Homepage:
- Size: 1.65 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# Spends Tracker
A personal purchase and warranty tracking application with receipt/file management.
## Overview
Track your purchases, manage warranties, and analyze spending patterns. Upload receipts, manuals, and photos with automatic deduplication storage.
## Tech Stack
| Frontend | Backend | Storage |
| ---------------- | -------------------- | -------------------------------- |
| Vite + Alpine.js | FastAPI + SQLAlchemy | SQLite (dev) / PostgreSQL (prod) |
| Bootstrap 5 | Pydantic | Hash-sharded files |
| Chart.js | Uvicorn | Reference counting |
## Documentation
- [Documentation Hub](docs/) - Complete documentation collection
- [API Documentation](docs/API.md) - Complete REST API reference
- [System Architecture](docs/ARCHITECTURE.md) - Architecture overview and design
- [Development Plan](docs/DEVELOPMENT.md) - Roadmap and development phases
- [Security Policy](docs/SECURITY.md) - Security guidelines and vulnerability reporting
- [Architecture Diagram](docs/DIAGRAM.md) - Visual system architecture
- [Backend Documentation](backend/README.md) - Backend-specific implementation details
## Security
For security vulnerabilities, please report to **oss@mailite.com** or create a private GitHub security advisory.
## Quick Start
### Prerequisites
- Node.js 16+
- Python 3.10+
### Installation
```bash
# Install frontend dependencies
npm install
# Install backend dependencies
cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cd ..
```
### Configure Ports (Optional)
Default ports are **3030** (frontend) and **3031** (backend). To customize, edit the `.env` files:
**`.env`** (frontend):
```env
VITE_PORT=3030
VITE_API_URL=http://localhost:3031
```
**`backend/.env`** (backend):
```env
PORT=3031
FRONTEND_URL=http://localhost:3030
```
### Run Development Environment
**Terminal 1 - Frontend:**
```bash
npm run dev -- --host 0.0.0.0
```
**Terminal 2 - Backend:**
```bash
cd backend
source venv/bin/activate
uvicorn app.main:app --reload --host 0.0.0.0 --port 3031
```
| Service | Default URL |
| ----------- | -------------------------- |
| Frontend | http://localhost:3030 |
| Backend API | http://localhost:3031/api |
| API Docs | http://localhost:3031/docs |
## Features
- **Purchase Tracking**: Product details, price, retailer, brand
- **File Management**: Upload receipts, manuals, photos with deduplication
- **Warranty Tracking**: Auto-expiry detection
- **Analytics**: Spending trends, retailer/brand distribution
- **Data Import/Export**: JSON and CSV support
## Project Structure
```
spends/
├── src-modern/ # Frontend source (Vite + Alpine.js)
│ ├── scripts/ # Alpine.js components
│ └── styles/scss/ # SCSS styles
├── backend/ # FastAPI backend
│ ├── app/ # Routes, models, schemas
│ └── migrations/ # Alembic migrations
├── dist-modern/ # Production build (auto-generated)
└── uploads/ # File storage (hash-sharded)
```
## Key Commands
```bash
# Frontend
npm run dev # Development server
npm run build # Production build
# Backend
cd backend
alembic upgrade head # Run database migrations
uvicorn app.main:app --reload --host 0.0.0.0 --port 3031
# Testing
pytest # Run backend tests
```
## License
MIT