Biomedical Knowledge Graph for Disease Mechanisms

Full-Stack Interactive Sandbox & Synthetically Minded AI Co-Pilot

Welcome to the Biomedical Knowledge Graph for Disease Mechanisms. This application is a full-stack, clinically-minded research workspace and interactive canvas designed for software developers and biomedical researchers. It provides a visual playground for modeling complex molecular interrelations, testing semantic graph queries using Cypher-like syntax sandbox matching, identifying the shortest regulatory pathway cascades back-to-back, and enlisting the reasoning capabilities of the Gemini model (gemini-3.5-flash) via server-side secure endpoints.

---

🔬 Domain Architecture for Researchers

This platform organizes public biomedical insights and clinical data into a Heterogeneous Information Network (HIN). This enables researchers to break down complex pathologies into modular nodes and directed synaptic links rather than reading unstructured PDF publications.

                  [:TREATS]
    [ Drug ] ─────────────────> [ Disease ]
        │                            ▲
        │ [:TARGETS]                 │ [:DISRUPTED_IN]
        ▼                            │
    [ Gene ] ─────────────────> [ Pathway ]
                 [:PART_OF]

1. Unified Node Schema (Entity Typologies)

Four core biomedical entities are simulated with dynamic schema attributes:

• Gene: Active cellular proteins, enzymes, or genomic biomarkers. Attributes include chromosomal location, genomic symbols (symbol), official biological descriptions, and organic markers.
• Drug: Pharmaceutical Compounds and biologics. Attributes include chemical drug classification (class), FDA approval timeline annotations (approvalYear), and mechanisms of action.
• Disease: Clinical pathologies, syndromes, or oncological states. Attributes include clinical classification category (subClass), population prevalence stats (prevalence), and phenotypic symptoms.
• Pathway: Intracellular signal cascades, metabolic modules, or transduction networks. Attributes include organism restrictions (organism) and KEGG Database references (keggId).

2. Supported Synaptic Mechanisms (Relationship Typologies)

Connections are directional, representing physical bindings, clinical efficacy, expression controls, or disease pathways:

• TARGETS: High-affinity binding action site (Drug $\rightarrow$ Gene).
• TREATS: Pathological suppression or clinical intervention (Drug $\rightarrow$ Disease).
• ASSOCIATED_WITH: Overexpression, mutations, or biomarkers linked through study (Gene $\rightarrow$ Disease).
• PART_OF: Intracellular signal membership or kinase cascades (Gene $\rightarrow$ Pathway).
• DISRUPTED_IN: Cellular pathway malfunction contributing directly to pathophysiology (Pathway $\rightarrow$ Disease).
• INTERACTS_WITH: Direct protein-protein dynamic interactions (Gene $\leftrightarrow$ Gene).

---

🛠️ Computing & Code Architecture for Developers

The codebase employs a modern React client connected to a secure full-stack Node/Express proxy, making it ready to scale from sandbox mockups to full Postgres (via Cloud SQL/Drizzle) or physical Neo4j graph schemas.

1. BFS Shortest Path Engine (/src/utils/pathFinder.ts)

The shortest regulatory cascade is calculated in-browser using a Breadth-First Search (BFS) algorithm tailored for undirected neighbors traversal over the adjacency matrix. Once nodes are selected:

1. Adjacency List Formulation: Relationships are converted into undirected linking edges to ensure traversal upstream and downstream.
2. Queue Traversal & Visited Boundary: A queue-based tracking strategy operates back to ensure $O(V + E)$ linear time complexity.
3. Backtracking Trail: Parents are recorded dynamically. If the destination node is reached, the exact chain of GraphNode and GraphRelationship entities is reconstructed and formatted.

export function findShortestPath(
  nodes: GraphNode[],
  relationships: GraphRelationship[],
  startId: string,
  endId: string
): ShortestPathResult;

2. Node/Express Server-Side Secure API (/server.ts)

To secure API credentials while calling models, a full-stack configuration proxies raw prompts:

• Lazy Google GenAI Initialization: Uses the official @google/genai TypeScript SDK. The client is instantiated lazily during the first active request, ensuring the app won't crash during deployment setup if environmental secrets aren't bound.
• Model Parameter Tuning: The engine utilizes the high-throughput gemini-3.5-flash model, configured with custom structural system instructions tailored for clinical computational biology tasks.
• Topological Context injection: Injected JSON sub-graphs are mapped directly into system instructions, giving the model precise contextual metadata about node attributes and relationships:

  {
    "model": "gemini-3.5-flash",
    "systemInstruction": "You are an expert computational biologist... Analyze using this active graph context..."
  }

3. Client State Synchronization Flow

[User Selects Start & End Nodes]
         │
         ▼
[React invokes findShortestPath()]
         │
         ├──► Graph Canvas (Instantly glows target nodes and matching connection links)
         └──► AI Discovery Panel (Compiles JSON parameters of all node/rel attributes)
                   │
                   ▼ [User clicks "Analyze with Gemini"]
      [Client fetches /api/gemini/analyze]
                   │
                   ▼ [Express server binds GEMINI_API_KEY]
      [Gemini Model synthesizes reasoning]
                   │
                   ▼ [Client UI processes stream response]
[Biological Significance & Clinical Reasoning Block displays markdown analysis]

---

💻 Technical Setup & Local Execution

1. Dependency Configurations

Make sure Node.js (v18+) is installed. Install all pre-configured dependencies inside the sandbox environment:

npm install

2. Spin Up Local Servers

Launch Node.js, Express, and Vite simultaneously with live source file compilation:

npm run dev

The server will boot up and bind to http://localhost:3000. Direct your browser to access the active dashboard.

3. Bun/Vite Production Build Compilation

To produce optimized static assets and bundle the Express server into standard Node-executable CommonJS bundles, execute:

npm run build

This performs a two-stage process:

1. Vite Build: Compiles React, Vite, and tailwind assets into static files inside the /dist output directory.
2. Esbuild Bundling: Bundles backend dependencies securely into /dist/server.cjs while handling TypeScript type-stripping automatically, bypassing ES Modules filesystem constraints.

To start the compiled production build:

npm run start

---

📈 Shipping Beyond Sandbox: Physical Graph Databases

Once your hypotheses are verified in this sandbox environment, we provide easy transition matrices to run high-throughput Graph Neural Networks (GNNs) or query millions of nodes in physical production environments.

📁 Dynamic Cypher Export (Neo4j Browser)

1. Navigate to the Production Deployment tab inside the application.
2. The engine dynamically parses the live state of your canvas elements (including any custom node boundaries you synthesized manually with the layout form) and constructs a multi-line Cypher Match / Create Script.
3. Click Copy Code and paste the output straight into any Neo4j Workspace, AuraDB interactive shell, or Cypher compiler:

   CREATE (AlzheimersDisease:Disease {id: 'Alzheimer\'s Disease', label: 'Alzheimer\'s Disease', description: 'Chronic neurodegenerative dementia...'});
   CREATE (PSC9:Gene {id: 'PCSK9', label: 'PCSK9', symbol: 'PCSK9', chromosome: '1p32.3'});
   MATCH (s {id: 'Alzheimer\'s Disease'}), (t {id: 'PCSK9'}) CREATE (s)-[:ASSOCIATED_WITH {description: 'Downregulation risk parameters...'}]->(t);

🐍 High-Throughput CSV Ingestion with python-driver

To read hundreds of thousands of drug targets from files into your Neo4j Cluster, use our production-grade Python database connector:

import os
from neo4j import GraphDatabase

NEO4J_URI = os.getenv("NEO4J_URI", "neo4j+s://xxxxxx.databases.neo4j.io")
NEO4J_USER = os.getenv("NEO4J_USER", "neo4j")
NEO4J_PASSWORD = os.getenv("NEO4J_PASSWORD", "your_password_here")

class BiomedicalIngester:
    def __init__(self, uri, user, password):
        self.driver = GraphDatabase.driver(uri, auth=(user, password))

    def close(self):
        self.driver.close()

    def ingest_association(self, gene, disease, score, text):
        query = """
        MERGE (g:Gene {id: $gene})
        MERGE (d:Disease {id: $disease})
        MERGE (g)-[r:ASSOCIATED_WITH {score: toFloat($score), description: $text}]->(d)
        """
        with self.driver.session() as s:
            s.run(query, gene=gene, disease=disease, score=score, text=text)

---

⭐ Key Highlights of the Co-Pilot Workspace

• Synaptic Inspector: Clicking any element triggers biological annotations, immediate gene properties summaries, and targeted AI formulation triggers.
• Visual Glow Effects: Matching queries run on the Cypher Console instantly trigger interactive CSS-glowing visual indicators across relative pathways on the SVG network canvas.
• Graceful Degrade Systems: If the API key environment variable is not defined, clear error boundaries explain how to bind keys in settings, preventing broken UI states. *,