Skip to main content

​
Getting Started for Developers

This guide will help you set up your development environment and start contributing to the Quran Knowledge Graph project.

​
Prerequisites

Before you begin, make sure you have the following installed:
  • Python 3.9+ - For backend development
  • Node.js 16+ - For frontend development
  • Docker - For containerized development
  • Git - For version control

​
Setting Up Your Development Environment

​
1. Clone the Repository

git clone https://github.com/muhajirdev/quran-labs.git
cd quran-knowledge-graph

​
2. Backend Setup

​
Create a Python Virtual Environment

# Create a virtual environment
python -m venv venv

# Activate the virtual environment
# On Windows
venv\Scripts\activate
# On macOS/Linux
source venv/bin/activate

​
Install Dependencies

pip install -r requirements.txt

​
Set Up Environment Variables

Create a .env file in the root directory: 
# Database
DATABASE_URL=kuzu://localhost:5432/quran_graph

# API
API_PORT=8000
DEBUG=True
SECRET_KEY=your_secret_key_here

# Vector Embeddings
EMBEDDING_MODEL=bert-base-multilingual-cased

​
Run the Backend Server

cd backend
uvicorn app.main:app --reload
The API will be available at http://localhost:8000.

​
3. Frontend Setup

​
Install Dependencies

cd frontend
npm install

​
Set Up Environment Variables

Create a .env.local file in the frontend directory: 
NEXT_PUBLIC_API_URL=http://localhost:8000

​
Run the Frontend Development Server

npm run dev
The frontend will be available at http://localhost:3000.

​
4. Docker Setup (Alternative)

If you prefer to use Docker for development: 
# Build and start all services
docker-compose up -d

# View logs
docker-compose logs -f
This will start:
  • The backend API at http://localhost:8000
  • The frontend at http://localhost:3000
  • The Kuzu database at localhost:5432

​
Project Structure

quran-knowledge-graph/
├── backend/                # Python backend API
│   ├── app/                # Main application code
│   │   ├── api/            # API endpoints
│   │   ├── core/           # Core functionality
│   │   ├── db/             # Database models and queries
│   │   ├── embeddings/     # Vector embedding logic
│   │   └── main.py         # Application entry point
│   ├── tests/              # Backend tests
│   └── requirements.txt    # Python dependencies
├── frontend/               # Next.js frontend
│   ├── components/         # React components
│   ├── pages/              # Next.js pages
│   ├── public/             # Static assets
│   ├── styles/             # CSS styles
│   └── package.json        # Node.js dependencies
├── data/                   # Data processing scripts
│   ├── sources/            # Raw data sources
│   ├── processed/          # Processed data
│   └── scripts/            # Data processing scripts
├── docs/                   # Documentation
└── docker-compose.yml      # Docker configuration

​
Development Workflow

​
1. Create a Feature Branch

git checkout -b feature/your-feature-name

​
2. Make Your Changes

Implement your changes, following the project’s coding standards.

​
3. Run Tests

# Backend tests
cd backend
pytest

# Frontend tests
cd frontend
npm test

​
4. Submit a Pull Request

  1. Push your changes to your fork
  2. Create a pull request against the main repository
  3. Fill out the pull request template with details about your changes
  4. Wait for code review and address any feedback

​
Working with the Graph Database

​
Connecting to Kuzu

from kuzu import Connection

# Connect to the database
conn = Connection("path/to/database")

# Execute a Cypher query
result = conn.execute("MATCH (v:Verse) WHERE v.surah_number = 1 RETURN v")

# Process results
for row in result:
    print(row["v"])

​
Example Queries

Here are some example queries to help you get started:

​
Get a Verse by Reference

MATCH (v:Verse {verse_key: '1:1'})
RETURN v

​
Find Verses by Topic

MATCH (t:Topic {name: 'Patience'})<-[r:ADDRESSES_TOPIC]-(v:Verse)
RETURN v.verse_key, v.text_simple, r.relevance
ORDER BY r.relevance DESC
LIMIT 10

​
Find Words with the Same Root

MATCH (w:Word)-[:HAS_ROOT]->(r:RootWord {text_arabic: 'ر-ح-م'})
RETURN w.text_arabic, w.verse_key

​
Working with Vector Embeddings

​
Generating Embeddings

from app.embeddings.model import EmbeddingModel

# Initialize the embedding model
model = EmbeddingModel()

# Generate an embedding for text
text = "What does the Quran say about patience?"
embedding = model.generate_embedding(text)

# Use the embedding for similarity search
similar_verses = model.find_similar_verses(embedding, limit=5)

​
Vector Search in Cypher

// Find verses similar to a query embedding
MATCH (v:Verse)
WHERE v.embedding VECTOR_DISTANCE($query_embedding) < 0.2
RETURN v.verse_key, v.text_simple
ORDER BY v.embedding VECTOR_DISTANCE($query_embedding)
LIMIT 5

​
API Documentation

The API documentation is available at http://localhost:8000/docs when running the development server. For more detailed API documentation, see the API Reference.

​
Getting Help

If you need help or have questions:
  1. Check the Technical Documentation
  2. Join our Discord community
  3. Open an issue on GitHub

​
Next Steps