https://github.com/ddc/finances
Personal finance management app
https://github.com/ddc/finances
Last synced: 2 months ago
JSON representation
Personal finance management app
- Host: GitHub
- URL: https://github.com/ddc/finances
- Owner: ddc
- License: mit
- Created: 2026-04-02T17:49:23.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-03T20:07:35.000Z (2 months ago)
- Last Synced: 2026-04-04T08:50:00.312Z (2 months ago)
- Language: TypeScript
- Homepage:
- Size: 328 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
Personal finance management app
## Table of Contents
- [Stack](#stack)
- [Timezone Handling](#timezone-handling)
- [Setup](#setup)
- [Development](#development)
- [Running Tests](#running-tests)
- [Deployment](#deployment)
- [Local Development with Database](#local-development-with-database)
- [License](#license)
- [Support](#support)
---
## Stack
| Layer | Technology |
|-----------------|------------------------------------------------------|
| Backend | Django 6.0 + Django REST Framework |
| Frontend | React 19 + Vite + MUI + Recharts |
| Database | PostgreSQL |
| Auth | Token-based (DRF TokenAuthentication) |
| i18n | EN-US, PT-BR |
| Package Manager | uv (backend), bun (frontend) |
| Linting | ruff (backend), eslint (frontend) |
| Testing | pytest + testcontainers (backend), vitest (frontend) |
| Deploy | Docker Compose |
## Timezone Handling
| Layer | Timezone |
|--------------------|-----------------------------------------------------------------|
| **Database** | UTC (always) |
| **Django API** | Returns UTC strings |
| **React frontend** | Converts to browser's local timezone via `toLocaleDateString()` |
| **Django admin** | Uses `DJANGO_TIME_ZONE` from `.env` |
Timestamps are always stored in UTC. The frontend displays them in the user's browser timezone automatically. The
`DJANGO_TIME_ZONE` env var only affects the Django admin panel.
## Setup
### 1. Create database user and database
```sql
SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE datname = 'finances'
AND pid <> pg_backend_pid();
DROP
DATABASE IF EXISTS finances;
DROP ROLE if EXISTS finances;
CREATE
USER finances WITH PASSWORD 'finances';
CREATE
DATABASE finances OWNER finances;
GRANT ALL PRIVILEGES ON DATABASE
finances TO finances;
```
### 2. Configure environment
```bash
cp .env.example .env
# Edit .env with your values
```
Generate a secret key:
```bash
python3 -c "import secrets; print(secrets.token_urlsafe(50))"
```
### 3. Start the application
```bash
docker compose up -d --build
```
### 4. Create admin user
```bash
docker compose exec backend uv run --frozen --no-sync python manage.py seed_data
```
Default credentials:
- **Username:** admin
- **Password:** admin123
Or create one manually:
```bash
docker compose exec backend uv run --frozen --no-sync python manage.py createsuperuser
```
## Development
### Backend
Requires [UV](https://docs.astral.sh/uv/getting-started/installation/) to be installed.
```bash
cd backend
uv sync --all-groups
```
### Frontend
```bash
cd frontend
bun install
bun run dev
```
### Running tests
From the `backend/` directory:
```bash
# All tests
uv run poe tests
# Backend only
uv run poe test-backend # unit tests + coverage
uv run poe test-backend-integration # integration tests (testcontainers)
uv run poe test-backend-docker # docker tests (hadolint, compose)
# Frontend only
uv run poe test-frontend # unit tests
uv run poe test-frontend-integration # integration tests
# Linting
uv run poe linter-backend # ruff
uv run poe linter-frontend # eslint
# Update dependencies
uv run poe update-backend
uv run poe update-frontend
```
## Deployment
### Update and restart
```bash
./utilities/update.sh
```
### Start / Stop
```bash
./utilities/start.sh
./utilities/stop.sh
```
## Local development with database
For local development with a containerized PostgreSQL:
```bash
docker compose -f docker-compose-localdb.yml up -d
```
Set `.env`:
```
POSTGRES_HOST=finances_database
```
## License
Released under the [MIT License](LICENSE)
## Support
If you find this project helpful, consider supporting development.
