The central API gateway for the NassaQ document digitization platform. Handles authentication, file uploads, virtual path management, and OCR job dispatch.
This repository is the Backend Server component of NassaQ — an AI-powered platform that processes uploaded documents through bilingual (Arabic/English) OCR pipelines and makes them searchable.
The server is responsible for the full request lifecycle: authenticating users, accepting file uploads, storing files in Azure Blob Storage, recording metadata in Azure SQL Server, and publishing processing jobs to a Message Broker queue for the OCR worker to consume asynchronously.
For platform-wide documentation, see docs.
NassaQ is composed of three independently deployable services:
| Component | Repository | Technology |
|---|---|---|
| Backend Server | NassaQ/server (this repo) |
Python 3.11, FastAPI, SQLAlchemy 2.0 |
| OCR Worker | NassaQ/ocr-api |
Python 3.11, FastAPI, PaddleOCR, EasyOCR |
| User Interface | NassaQ/User_Interface |
React 18, TypeScript, Vite 5, Tailwind CSS |
Services communicate via REST (frontend → server) and AMQP (server → OCR worker via RabbitMQ or AzureBus). All persistent storage is on Azure managed services for now, we are planning to support local storage setup soon.
| Category | Technology | Purpose |
|---|---|---|
| Framework | FastAPI + Uvicorn | Async web framework and ASGI server |
| ORM | SQLAlchemy 2.0 (async, aioodbc) |
Database access layer |
| Primary Database | Azure SQL Server (ODBC 18) | Users, documents, paths, roles, audit logs |
| File Storage | Azure Blob Storage | Upload and retrieval of original documents |
| Message Broker | RabbitMQ (aio-pika) & AzureBus (azure-servicebus) |
Async job queue for OCR dispatch |
| Auth | python-jose + passlib[bcrypt] |
JWT tokens and password hashing |
| Validation | Pydantic v2 + Pydantic Settings | Request/response schemas and config |
| Package Manager | uv |
Dependency management and virtual environments |
| Tool | Version | Notes |
|---|---|---|
| Python | >= 3.11 | |
| uv | Latest | Package manager |
| Docker | 20+ | Required for RabbitMQ and containerized deployment |
| ODBC Driver 18 | Latest | SQL Server connectivity (installed automatically in Docker) |
Copy the example file and fill in your credentials:
cp .env.example .envEvery variable is documented inside .env.example. Two connection strings (SQL Server and MongoDB/Cosmos DB) are computed automatically from the individual fields — you do not set them directly.
1. Install dependencies
uv sync2. Start RabbitMQ (required — only if running in dev environment)
docker compose up rabbitmq -d3. Start the server
uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 --reloadThe server will be available at http://localhost:8000. Swagger UI is at http://localhost:8000/docs when ENVIRONMENT="dev".
# Build
docker build -t nassaq-server:latest .
# Run
docker run -d \
--name nassaq-server \
--env-file .env \
-p 8000:8000 \
nassaq-server:latestThe image uses a multi-stage build: a builder stage compiles dependencies, and a minimal runtime stage installs Microsoft ODBC Driver 18 and runs the app as a non-root user. Health check is GET / (returns 204 No Content) every 30 seconds.
To run the full platform (server + OCR worker + Message Broker) together, see the Deployment Guide.
All endpoints are versioned under /api/v1. Three authorization tiers are enforced:
| Route Group | Base Path | Description |
|---|---|---|
| Auth | /api/v1/auth |
Register, login (OAuth2 password flow), token refresh |
| Users | /api/v1/users |
Profile management (self) and user administration (admin) |
| Documents | /api/v1/docs |
File upload — stores to Blob, creates DB record, dispatches to OCR queue |
| Virtual Paths | /api/v1/paths |
Hierarchical folder management for organizing documents |
Full endpoint reference: docs/reference/api-endpoints/
uv sync --extra test
uv run pytestThe test suite covers:
- security functions tests.
- schemas function tests.
This project is a graduation project and is currently not accepting external contributions. The repository is on hold while the project is under academic review. Feel free to explore the code and documentation, but pull requests will not be reviewed at this time.
Full platform documentation is available at nassaq.github.io/docs covering the full details about the project, from system design to specific components guides.