Documentation Index
Fetch the complete documentation index at: https://docs.superquran.com/llms.txt
Use this file to discover all available pages before exploring further.
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
http://localhost:8000.
3. Frontend Setup
Install Dependencies
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
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
- 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
- Push your changes to your fork
- Create a pull request against the main repository
- Fill out the pull request template with details about your changes
- 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:
- Check the Technical Documentation
- Join our Discord community
- Open an issue on GitHub
Next Steps
