Skip to content

README.md

Latest commit

 

History

History
212 lines (147 loc) · 6.82 KB

README.md

File metadata and controls

212 lines (147 loc) · 6.82 KB
Raw

Essay Feedback Writer Project - Backend

언어 선택 / Language Selection:

한국어  ｜  English 

Requirements

  • Docker.
  • uv for Python package and environment management (replaces Poetry).

Local Development

  • Start the stack with Docker Compose:
docker compose up -d
  • Now you can open your browser and interact with these URLs:

Frontend, built with Docker, with routes handled based on the path: http://localhost:5173

Backend, JSON based web API based on OpenAPI: http://localhost:8000

Automatic interactive documentation with Swagger UI (from the OpenAPI backend): http://localhost:8000/docs API docs

Adminer, database web administration: http://localhost:8080 API docs

Traefik UI, to see how the routes are being handled by the proxy: http://localhost:8090

API docs

To check the logs, run:

docker compose logs

To check the logs of a specific service, add the name of the service, e.g.:

docker compose logs backend

General workflow

Dependencies are managed with uv.

From ./backend/ you can install all the dependencies with:

$ uv sync

To run commands in the virtual environment:

$ uv run pytest
$ uv run ruff check --fix

Make sure your editor is using the correct Python virtual environment.

Key backend directories

  • SQLAlchemy models: ./backend/app/models.py
  • API endpoints: ./backend/app/api/routes/ (4 routers: user, ielts, ksat, shared)
  • CRUD operations: ./backend/app/crud/ (per-entity modules)
  • Pydantic schemas: ./backend/app/schemas/
  • Multi-agent scoring: ./backend/app/agents/ (swarm, aggregator, builder, loader)
  • Rubric configs: ./backend/app/agents/configs/ (YAML rubrics per domain)

pre-commit setting

  1. Install pre-commit
apt install -y pre-commit
  1. Apply pre-commit
pre-commit install

Backend tests

To set up the test environment, run the following command:

$ docker compose -f docker-compose.yaml -f docker-compose.override.yaml -f docker-compose.test.yaml up

This will start the Test DB, which is isolated from the dev and prod databases.

It is recommended to use the test DB to keep the data separate during testing.

To run the backend tests, execute:

$ # Start an interactive session in the backend container
$ docker compose exec backend bash

$ bash ./scripts/test.sh

The tests run with Pytest, modify and add tests to ./backend/app/tests/.

If you use GitHub Actions the tests will run automatically.

Test Coverage

When the tests are run, a file htmlcov/index.html is generated, you can open it in your browser to see the coverage of the tests.

Migrations

As during local development your app directory is mounted as a volume inside the container, you can also run the migrations with alembic commands inside the container and the migration code will be in your app directory (instead of being only inside the container). So you can add it to your git repository.

Make sure you create a "revision" of your models and that you "upgrade" your database with that revision every time you change them. As this is what will update the tables in your database. Otherwise, your application will have errors.

  • Start an interactive session in the backend container:
$ docker compose exec backend bash

  • Alembic is already configured to import your SQLModel models from ./backend/app/models.py.

  • After changing a model (for example, adding a column), inside the container, create a revision, e.g.:

$ alembic revision --autogenerate -m "Add column last_name to User model"

  • Commit to the git repository the files generated in the alembic directory.

  • After creating the revision, run the migration in the database (this is what will actually change the database):

$ alembic upgrade head

Debugging with VSCode (Docker)

You can debug the backend running inside Docker using debugpy and VSCode's attach debugger.

Prerequisites

If debugpy is not yet installed in the running container:

docker-compose exec backend pip install debugpy

Debugging the running server

  1. Set DEBUG=true in your .env file
  2. Restart the backend: 
    docker-compose up -d backend
  3. The server will wait for the debugger to attach before starting
  4. Set breakpoints in VSCode, then press F5 and select "Attach to Docker Backend"

Debugging pytest

  1. Make sure DEBUG=false (or unset) in .env so the server isn't holding port 5678
  2. Run pytest with debugpy inside the container: 
    docker-compose exec backend python -m debugpy --listen 0.0.0.0:5678 --wait-for-client -m pytest app/tests/api/routes/test_ielts.py -v
  3. Set breakpoints in your test file, then press F5 and select "Debug Pytest in Docker"

VSCode launch.json

The .vscode/launch.json should contain:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to Docker Backend",
      "type": "debugpy",
      "request": "attach",
      "connect": { "host": "localhost", "port": 5678 },
      "pathMappings": [
        { "localRoot": "${workspaceFolder}/backend", "remoteRoot": "/app" }
      ]
    },
    {
      "name": "Debug Pytest in Docker",
      "type": "debugpy",
      "request": "attach",
      "connect": { "host": "localhost", "port": 5678 },
      "pathMappings": [
        { "localRoot": "${workspaceFolder}/backend", "remoteRoot": "/app" }
      ]
    }
  ]
}

Email Templates

The email templates are in ./backend/app/email-templates/. Here, there are two directories: build and src. The src directory contains the source files that are used to build the final email templates. The build directory contains the final email templates that are used by the application.

Before continuing, ensure you have the MJML extension installed in your VS Code.

Once you have the MJML extension installed, you can create a new email template in the src directory. After creating the new email template and with the .mjml file open in your editor, open the command palette with Ctrl+Shift+P and search for MJML: Export to HTML. This will convert the .mjml file to a .html file and now you can save it in the build directory.