MarketMind

Monorepo with a Next.js frontend, Flask API, and PostgreSQL, orchestrated with Docker Compose.

Prerequisites

• Docker and Docker Compose v2
• (Optional) Node.js and Python if you develop services outside Docker

Quick start

1. Copy environment defaults and adjust if needed:

   cp .env.example .env

2. Start all services (builds images on first run):

   docker compose up --build

This repo is optimized for faster container rebuilds:

• Backend image uses uv for Python dependency installation.
• Frontend image uses npm ci with a Docker cache mount for reliable rebuilds.
• Compose mounts use cache-friendly settings for local development.

Note: Bun can crash on some Linux arm64 Docker environments during install, so Docker uses npm by default for stability.

Useful commands:

# Rebuild only app images
docker compose build backend frontend

# Start without forcing a rebuild
docker compose up

# Recreate containers if dependency layer changed
docker compose up --build --force-recreate

3. Open the app:

   • Frontend: http://localhost:3000 — use the buttons to call the API.
   • Backend: http://localhost:5001/health
   • Postgres: localhost:5433 (credentials match .env)

Verify database read/write

• In the UI, click POST /db/write to insert a row, then GET /db/read to see the latest rows (up to 10).

• Or use curl:

   curl -s http://localhost:5001/db/write -H "Content-Type: application/json" \
    -d '{"message":"manual test"}'
   curl -s http://localhost:5001/db/read

Data persistence

Postgres files live in the Docker named volume postgres_data. Removing containers does not remove this volume unless you run docker compose down -v.

Connect Hex to local Postgres (ngrok TCP tunnel)

1. Verify ngrok account can open TCP endpoints:

   • If ERR_NGROK_8013 appears, complete account verification at ngrok dashboard.

2. Start postgres + tunnel:

   ./scripts/start-hex-ngrok.sh

3. Use printed values in Hex connection settings:

   • Name: Local Docker Postgres
   • Host: <ngrok host>
   • Port: <ngrok port>
   • Database/Username/Password: read from .env

4. Stop tunnel when finished:

   ./scripts/stop-hex-ngrok.sh

Project layout

• frontend/ — Next.js app (NEXT_PUBLIC_API_BASE_URL points at the Flask API from the browser).
• backend/ — Flask app; uses DATABASE_URL (hostname postgres inside Compose).
• db/schema.sql — applied automatically on first database initialization via /docker-entrypoint-initdb.d.

To re-run schema after the DB already exists, apply SQL manually or reset the volume (this deletes data):

docker compose down -v
docker compose up --build