Coding with AI - Sample Project

Prerequisites

• Python 3.14
• Node.JS >= LTS
• uv

Installing Dependencies

cd backend
uv sync

cd frontend
npm install

Testing the Code

cd backend
uv run ruff check # Linting the code
uv run mypy # Type checking the code
uv run pytest # Running the tests

cd frontend
npm run lint # Linting the code
npm run typecheck # Type checking the code
npm run test # Running the tests

Open API Specification

Generate the Open API specification file:

cd backend
uv run python scripts/export_openapi.py

Generate the API schema types:

cd frontend
npm run generate-types

Database Setup and Management

This project uses SQLAlchemy 2 as the ORM and Alembic for database migrations.

Database Configuration

The database URL is configured in app/settings.py and defaults to SQLite. You can override this by setting the DATABASE_URL environment variable or creating a .env file.

How to manage the database:

# Run all pending migrations
cd backend
uv run alembic upgrade head

After modifying models in app/models.py, create a new migration:

# Auto-generate migration from model changes
cd backend
uv run alembic revision --autogenerate -m "Description of changes"

# Review the generated migration file in alembic/versions/

# Then apply it:
uv run alembic upgrade head

Running the Project

To run the project, you must start the backend and the frontend in the background:

cd backend
uv run uvicorn app.main:app --reload

cd frontend
npm start

Note that the frontend (vite) contains a proxy to the backend API (see vite.config.ts).

Reverse Proxy Setup

docker run --rm -it -v ~/.mitmproxy:/home/mitmproxy/.mitmproxy -p 8080:8080 -p 8081:8081 mitmproxy/mitmproxy mitmweb --web-host 0.0.0.0 --listen-host 0.0.0.0 --listen-port 8080