CIVIS - AI Policy Document Compliance Audit Checker Backend Application

This is the backend system for CIVIS AI Policy Document Analysis — built with FastAPI, SQLAlchemy, Alembic, and modern tooling using uv for dependency management.

---

Setup Instructions

1. Install Python and uv

Make sure Python 3.10+ is installed.

Install uv (package manager + virtualenv):

curl -LsSf https://astral.sh/uv/install.sh | sh

Install WeasyPrint WeasyPrint depends on some system libraries to render fonts, images, and CSS properly.

   brew install cairo pango gdk-pixbuf libffi 

---

2. Clone the Repository

git clone https://github.com/civis-vote/draft-analyzer-be.git
cd civis-backend-policy-analyser

---

3. Environment Configuration (.env)

Create a .env file

# example .env 

# Database settings
DB_USER=username
DB_PASSWORD=password
DB_HOST=localhost
DB_PORT=5432
DB_NAME=db-name

# Azure  DeepSeek settings 
AZURE_DEEPSEEK_API_KEY=your-api-key
AZURE_DEEPSEEK_ENDPOINT=https://your-resource.endpoint
AZURE_DEEPSEEK_MODEL=your-model-name
AZURE_DEEPSEEK_DEPLOYMENT_NAME=your-deployment-name
AZURE_OPENAI_API_VERSION=your-api-version
LLM_CLIENT=ollama

4. Bootstrap the Project

make setup

This will:

• Create .venv
• Install base + AI + test dependencies
• Lock dependencies
• Generate requirements.txt

---

Run the FastAPI Server

make run

Visit:

• Swagger UI: http://localhost:8000/api/docs
• ReDoc: http://localhost:8000/redoc

---

Testing & Linting

Run Tests

make test

Run Tests with Coverage

make cov

Run Linter

make lint

Auto-fix Formatting & Style Issues

make fix

---

Database (Postgres via Docker) + Alembic

Build & Start DB

make db-build
make db-up

Run Alembic Migrations

1. Initialize alembic (first time only):

alembic init -t async src/civis_backend_policy_analyser/alembic

2. Create a revision:

alembic revision --autogenerate -m "Initial schema"

3. Apply migration:

alembic upgrade head

DB Utility Commands

make db-logs     # View logs
make db-psql     # Open psql shell
make db-down     # Stop and remove container

---

Seed Initial Data

make seed

This runs seed_data.py inside the virtual environment.

---

Project Structure

.
├── src/
│   └── civis_backend_policy_analyser/
│       ├── alembic/                  # Alembic migrations
│       ├── api/                      # FastAPI routes (entrypoints, routers)
│       ├── core/                     # App config, DB setup, constants
│       ├── model/                    # SQLAlchemy ORM models
│       ├── schemas/                  # Pydantic schemas (request/response)
│       ├── utils/                    # Helper functions, formatters, etc.
│       ├── views/                    # Route logic (e.g., CRUD handlers)
│       └── __init__.py
├── pyproject.toml                   # Dependency & build config
├── Makefile                         # Task automation
├── requirements.txt                 # (auto-generated by uv)
├── seed_data.py                     # DB seeding script
└── README.md                        # Project documentation

---

Developer Notes

• uv manages dependencies via pyproject.toml with groups: [project], ai, test.
• No manual activation of .venv is required when using uv run.
• Prefer make targets for consistent workflows.
• make setup is the fastest way to bootstrap everything from scratch.
• make quick-start is for the quick start with sample data in database if docker running in local.

---

Quick Commands Reference

Command	Action
make quick-start	Start full application with sample data
make setup	Full setup: venv + deps + lock + freeze
make run	Start FastAPI app
make lint	Run linter
make fix	Auto-fix lint issues
make test	Run unit tests
make cov	Run tests with coverage
make revision	Create alembic schema as per models
make seed	Seed initial data
make db-up	Start DB container
make db-down	Stop DB container
make db-psql	Open DB shell inside container

---