Coffee Exp ☕

A personal brewing journal for the curious coffee lover.

"Life's too short for bad coffee — and too rich not to remember the good ones."

Coffee Exp is a minimalistic app built to help coffee enthusiasts track their brewing experiences — every pour-over, every espresso shot, every lazy French press Sunday morning. Log what you brewed, how you brewed it, rate the result, and over time build a personal archive of your coffee journey.

Born out of a simple need: the creator loves coffee and kept forgetting which beans, ratios, and methods made that one perfect cup. Coffee Exp fixes that.

---

What's on the menu

• Brewing journal — Record each session with method, grams, water volume, and free-form notes
• 5-axis ratings — Score flavor, acidity, aroma, appearance, and bitterness on a 1–5 scale (overall calculated automatically)
• Coffee & brand catalog — Keep a personal inventory of beans you've tried, organized by brand and country
• Location tagging — Remember where that great cup happened (GPS on mobile)
• Multi-platform — Web app for the desktop, mobile app for brewing on the go
• Clean & cozy UI — Material UI on web, React Native Paper on mobile — no clutter, just coffee

---

Tech stack

Backend

Web

Mobile

Infrastructure

---

Getting started

Prerequisites

• Docker & Docker Compose
• Node.js 20+ (for web/mobile)
• uv (for the API)

Quickstart with Docker (recommended)

# Clone the repo
git clone https://github.com/henriquecaltram/coffee_exp.git
cd coffee_exp

# Spin up everything — API, web, and databases
docker-compose up

Service	URL
API	http://localhost:8000
Web	http://localhost:3000
PostgreSQL Dev	localhost:5432

Manual setup

API

cd api

# Install dependencies
make install        # or: uv sync

# Create your .env from the example
cp .env.example .env

# Run database migrations
make migrate

# Start the dev server (http://localhost:8000)
make dev

Available make commands:

Command	Description
make install	Install dependencies
make dev	Start dev server
make test	Run tests
make test-cov	Tests with HTML coverage
make format	Format code with Black
make lint	Check formatting
make migrate	Run pending migrations
make migrate-new name="..."	Create a new migration
make migrate-down	Rollback last migration

Web

cd web

# Install dependencies
npm install

# Start dev server with HMR (http://localhost:3000)
npm run dev

Other scripts: npm run build, npm run lint, npx vitest run

Mobile

cd mobile

# Install dependencies
npm install

# Start Expo dev server
npm start

# Or run on a specific platform
npm run ios
npm run android

Environment variables

API (api/.env)

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/coffee_exp_dev
TEST_DATABASE_URL=postgresql://postgres:postgres@localhost:5433/coffee_exp_test
SECRET_KEY=change-me-in-production

Web — set VITE_API_URL to point to the API (defaults to http://localhost:8000 in Docker).

---

Project structure

coffee_exp/
├── api/                  # FastAPI backend
│   ├── app/
│   │   ├── models/       # SQLModel database models
│   │   ├── schemas/      # Pydantic request/response schemas
│   │   ├── routes/       # API endpoint handlers
│   │   ├── services/     # Business logic
│   │   └── database/     # DB connection & session
│   ├── migrations/       # Alembic migrations
│   ├── tests/
│   └── Makefile
├── web/                  # React + Vite frontend
│   └── src/
│       ├── components/
│       ├── pages/
│       ├── contexts/
│       └── api/
├── mobile/               # Expo + React Native app
│   └── app/
├── docker-compose.yml
└── .github/workflows/    # CI pipelines

---

License

This project is licensed under the MIT License.

---

Now go brew something wonderful.