> ## 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 > Guide to setting up your development environment and contributing to the Quran Knowledge Graph # 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 ```bash theme={null} git clone https://github.com/muhajirdev/quran-labs.git cd quran-knowledge-graph ``` ### 2. Backend Setup #### Create a Python Virtual Environment ```bash theme={null} # 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 ```bash theme={null} 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 ```bash theme={null} cd backend uvicorn app.main:app --reload ``` The API will be available at `http://localhost:8000`. ### 3. Frontend Setup #### Install Dependencies ```bash theme={null} 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 ```bash theme={null} npm run dev ``` The frontend will be available at `http://localhost:3000`. ### 4. Docker Setup (Alternative) If you prefer to use Docker for development: ```bash theme={null} # 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 ```bash theme={null} git checkout -b feature/your-feature-name ``` ### 2. Make Your Changes Implement your changes, following the project's coding standards. ### 3. Run Tests ```bash theme={null} # 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 ```python theme={null} 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 ```cypher theme={null} MATCH (v:Verse {verse_key: '1:1'}) RETURN v ``` #### Find Verses by Topic ```cypher theme={null} 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 ```cypher theme={null} MATCH (w:Word)-[:HAS_ROOT]->(r:RootWord {text_arabic: 'ر-ح-م'}) RETURN w.text_arabic, w.verse_key ``` ## Working with Vector Embeddings ### Generating Embeddings ```python theme={null} 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 ```cypher theme={null} // 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](/api-reference/introduction). ## Getting Help If you need help or have questions: 1. Check the [Technical Documentation](/technical/graph-database) 2. Join our [Discord community](https://discord.gg/your-invite-link) 3. Open an issue on GitHub ## Next Steps * Learn about the [System Architecture](/developers/architecture) * Explore the [Graph Database Implementation](/technical/graph-database) * Read the [Contributing Guidelines](/developers/contributing)