Staqs

Personal Finance for Hustlers - A personal finance application for people with W-2 income and side hustles.

Overview

Staqs is a full-stack personal finance application built with:

• Frontend: SvelteKit + TypeScript + TailwindCSS
• Backend: Node.js + Fastify + TypeScript
• Database: PostgreSQL 15 + Prisma
• Infrastructure: Docker + Docker Compose

Getting Started

Prerequisites

• Docker and Docker Compose
• Node.js 20+ (for local development)
• PostgreSQL 15+ (or use Docker)

Quick Start

1. Clone the repository:

   git clone https://github.com/HLLMR/staqs.git
   cd staqs

2. Copy environment file:

   cp .env.example .env

3. Configure environment variables: Edit .env and set:

   • POSTGRES_PASSWORD: Strong password for database
   • JWT_SECRET and JWT_REFRESH_SECRET: Generate with openssl rand -base64 32
   • SMTP_*: Your email service credentials
   • FRONTEND_URL and API_URL: Your domain URLs

4. Start services:

   docker compose up -d

5. Run database migrations:

   docker compose run --rm backend npm run prisma:deploy

6. Seed default categories:

   docker compose run --rm backend npm run prisma:seed

7. Access the application:

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:4000
   • Health check: http://localhost:4000/health

Development

For local development without Docker:

Backend:

cd backend
npm install
npm run prisma:generate
npm run dev

Frontend:

cd frontend
npm install
npm run dev

Project Structure

staqs/
├── backend/          # Node.js/Fastify API
├── frontend/         # SvelteKit application
├── database/         # Database initialization scripts
├── infrastructure/   # Deployment and setup scripts
├── docker-compose.yml
└── .env.example

Docker Services

• postgres: PostgreSQL 15 database
• backend: Fastify API server (port 4000)
• frontend: SvelteKit application (port 3000)

Network Configuration

This project uses the staqs-network Docker network. To connect NGINX Proxy Manager:

docker network connect staqs_staqs-network nginx-proxy-manager

Then configure the proxy to use staqs-web:3000 as the upstream (or staqs-web:80 if using the Node adapter).

Documentation

• ARCHITECTURE.md - System architecture
• DEPLOYMENT.md - Production deployment guide
• API.md - API documentation
• DATA_MODEL.md - Database schema
• SECURITY.md - Security practices
• ROADMAP.md - Development roadmap and progress
• .reference/Staqs UI-UX Plan.md - Comprehensive UI/UX design plan

License

MIT