### PHASE 1: REQUIREMENTS AND DOMAIN ANALYSIS 🔍 ### 1.1 Business and Research Objectives The system must create a unified pharmaceutical research knowledge infrastructure. Primary objectives: * Connect fragmented pharmaceutical research information. * Identify relationships between drugs, diseases, compounds, and clinical trials. * Discover potential therapeutic connections. * Support multi-hop research investigations. * Provide evidence-backed answers with source attribution. * Allow researchers to explore connections between scientific publications. * Support continuously updated research information. Example research question: "Which compounds are being investigated for treating Alzheimer's disease, and which clinical trials provide supporting evidence?" Expected system behavior: * Identify Alzheimer's disease. * Retrieve connected compounds. * Find associated drugs and clinical trials. * Identify relevant publications. * Retrieve evidence and provenance. * Return a ranked, traceable result. ### 1.2 Domain Analysis Primary domain: Pharmaceutical Research Intelligence Research Knowledge Layer Scientific publications, clinical evidence, trial records Entity Layer Drugs, diseases, researchers Relationship Layer Treatment, investigation, authorship Knowledge Retrieval Layer Graph traversal, vector search, GraphRAG Application Layer Research APIs, analytics, evidence exploration ### 1.3 Functional Requirements | ID | Requirement | Priority | | ----- | ----------------------- | -------- | | FR-01 | Document ingestion | Critical | | FR-02 | Entity extraction | Critical | | FR-03 | Relationship extraction | Critical | | FR-04 | Entity resolution | Critical | | FR-05 | Graph construction | Critical | | FR-06 | Graph search | High | | FR-07 | Vector retrieval | High | | FR-08 | GraphRAG answers | High | | FR-09 | Provenance tracking | Critical | | FR-10 | Tenant access control | Critical | | FR-11 | Graph analytics | Medium | | FR-12 | Incremental updates | High | ### 1.4 Non-Functional Requirements * Reliability: Failed ingestion jobs must be recoverable. * Scalability: Support the proposed 5-million-node and 20-million-edge target. * Security: Enforce tenant-level access restrictions. * Traceability: Every extracted fact must retain its source. * Maintainability: Separate ingestion, extraction, graph storage, and retrieval services. * Performance: Common retrieval requests should target less than 2 seconds. * Consistency: Prevent unsupported relationships from entering the production graph. ### 1.5 Expected Graph Query Patterns | Query pattern | Example | | -------------- | ------------------------------------------- | | Entity lookup | Find a drug by name | | One-hop | Find diseases associated with a drug | | Two-hop | Drug → Compound → Target | | Multi-hop | Disease → Compound → Trial → Publication | | Semantic | Find research about neurodegeneration | | Evidence-based | Find publications supporting a relationship | | Temporal | Find trials conducted between 2022–2026 | ### 1.6 Data Quality Constraints * Drug identifiers must be normalized. * Disease entities must use canonical terminology identifiers where available. * Trial records must retain trial registration identifiers. * Publications must retain DOI or PMID when available. * Relationships must have source evidence. * Contradictory findings must not be silently overwritten. * Entity merges must preserve original identifiers. ### 1.7 Initial Scale Estimation Proposed design capacity | Metric | Initial target | | -------------------------------- | ----------------- | | Entities | 5 million | | Relationships | 20 million | | Average relationships per entity | 4 | | Initial ingestion | 100,000 documents | | Concurrent API users | 500 | | Common retrieval latency | Under 2 seconds | | Data updates | Incremental | These are project targets, not measured performance results. ### 1.8 Identified Risks | Risk | Impact | Mitigation | | --------------------------- | -------- | ------------------------------------ | | Incorrect entity extraction | High | Confidence thresholds and validation | | Drug name ambiguity | High | Canonical identifiers | | Unsupported medical claims | Critical | Evidence-backed relationships | | Duplicate publications | Medium | DOI/PMID deduplication | | Conflicting research | High | Temporal and provenance tracking | | Unauthorized tenant access | Critical | Tenant-aware authorization | ### 1.9 Phase 1 Acceptance Criteria * Business objectives identified. * Domain boundaries established. * Source formats identified. * Functional requirements defined. * Non-functional requirements defined. * Query patterns documented. * Initial graph scale established. * Data risks identified. Phase 1 Complete ### PHASE 2: KNOWLEDGE DOMAIN MODELING 🧩 ### 2.1 Domain Boundaries The knowledge graph will cover five interconnected domains: * Pharmaceutical entities. * Biomedical concepts. * Clinical research. * Scientific publications. * Research organizations. The initial version will not attempt to model complete patient medical records or provide clinical decision-making. ### 2.2 Core Entity Categories | Entity | Description | Example | | ------------- | ----------------------------------- | --------------------- | | Drug | Pharmaceutical product or substance | Donepezil | | Compound | Chemical or biological compound | Experimental compound | | Disease | Medical condition | Alzheimer's disease | | Target | Biological target | BACE1 | | ClinicalTrial | Registered clinical investigation | NCT identifier | | Researcher | Scientific author | Research scientist | | Institution | Research organization | University | | Publication | Scientific article | PMID record | | Study | Research investigation | Phase II study | | Mechanism | Biological mechanism | Enzyme inhibition | ### 2.3 Relationship Categories | Relationship | Direction | Meaning | | --------------- | ------------------------ | ---------------------- | | TREATS | Drug → Disease | Therapeutic indication | | TARGETS | Drug → Target | Biological target | | INVESTIGATES | Trial → Compound | Trial investigation | | AUTHORED_BY | Publication → Researcher | Authorship | | CONDUCTED_AT | Trial → Institution | Trial location | | ASSOCIATED_WITH | Compound → Disease | Reported association | | REPORTS | Publication → Finding | Research finding | | PARTICIPATES_IN | Researcher → Trial | Trial participation | | HAS_MECHANISM | Drug → Mechanism | Mechanism of action | | STUDIES | Publication → Study | Study documentation | ### 2.4 Domain Hierarchy ```text Pharmaceutical Research │ ├── Pharmaceutical Entities │ ├── Drug │ ├── Compound │ └── Target │ ├── Biomedical Concepts │ ├── Disease │ └── Mechanism │ ├── Clinical Research │ ├── Clinical Trial │ └── Study │ └── Research Knowledge ├── Publication ├── Researcher └── Institution ``` ### 2.5 Entity Attribute Definitions Drug ```json { "canonical_id": "drug:example001", "name": "Example Drug", "generic_name": "Example", "drug_class": "Experimental", "external_ids": [], "aliases": [], "created_at": "2026-11-14T00:00:00Z" } ``` Disease ```json { "canonical_id": "disease:example001", "name": "Example Disease", "ontology_id": null, "aliases": [], "disease_category": "Neurological", "created_at": "2026-11-14T00:00:00Z" } ``` Clinical Trial ```json { "canonical_id": "trial:NCT00000001", "registry_id": "NCT00000001", "phase": "Phase II", "status": "Recruiting", "start_date": "2026-01-01", "source": "Clinical Trial Registry" } ``` These are illustrative records, not verified real-world research findings. ### 2.6 Naming Conventions * Entity labels: PascalCase. * Property names: snake_case. * Relationship names: UPPER_SNAKE_CASE. * Internal identifiers: UUID or deterministic canonical identifiers. * External identifiers: Preserve source-specific namespaces. ### 2.7 Domain Constraints * One publication can have multiple authors. * One clinical trial can investigate multiple compounds. * One compound can be investigated across multiple trials. * A drug may have multiple biological targets. * A disease may be connected to multiple research findings. * Relationships must preserve evidence and context. Phase 2 Complete ### PHASE 3: ENTITY EXTRACTION ENGINE 🔬 ### 3.1 Architecture The extraction engine transforms unstructured and structured pharmaceutical information into normalized entity records. ```text Source Documents | v Document Parser | v Text Normalization | v Entity Recognition | v Entity Classification | v Attribute Extraction | v Canonicalization | v Validation Engine | v Entity Candidate Store ``` ### 3.2 Extraction Components | Component | Technology | Responsibility | | -------------------- | --------------------------- | ----------------------------- | | NER | SciSpaCy / Transformers | Identify biomedical entities | | Classification | Fine-tuned transformer | Assign entity types | | Attribute extraction | LLM + rules | Extract structured properties | | Normalization | Terminology mappings | Normalize names | | ID resolution | External identifier mapping | Resolve canonical IDs | | Validation | Pydantic | Validate records | ### 3.3 Entity Recognition Example source sentence: "Researchers evaluated compound ABC-101 as a potential inhibitor of BACE1 in Alzheimer's disease models." Expected extracted candidates: ```json [ { "text": "ABC-101", "entity_type": "Compound", "confidence": 0.98 }, { "text": "BACE1", "entity_type": "Target", "confidence": 0.97 }, { "text": "Alzheimer's disease", "entity_type": "Disease", "confidence": 0.99 } ] ``` Confidence values are illustrative. ### 3.4 Attribute Extraction For each entity, extract: * Canonical name. * Aliases. * External identifiers. * Entity category. * Relevant attributes. * Source document ID. * Mention position. * Extraction model version. * Confidence score. ### 3.5 Entity Normalization Example: | Original text | Normalized entity | | ----------------- | ------------------- | | AD | Alzheimer's disease | | Alzheimer Disease | Alzheimer's disease | | Alzheimer's | Alzheimer's disease | | BACE-1 | BACE1 | Normalization must use contextual evidence rather than simple string replacement. ### 3.6 Canonical Identifier Generation Preferred identifier hierarchy: * Valid external identifier. * Domain ontology identifier. * Verified registry identifier. * Internal deterministic identifier. Example: ```text disease:mondo:0004975 drug:rxnorm:12345 trial:clinicaltrials:NCT00000001 publication:pubmed:12345678 ``` Do not assign an external identifier based solely on a similar name. ### 3.7 Confidence Scoring Proposed scoring model: C = 0.35N + 0.25T + 0.25X + 0.15S Where: * N = NER confidence. * T = Type classification confidence. * X = Contextual extraction confidence. * S = Source reliability score. All inputs are normalized to 0–1. Suggested routing: | Score | Action | | ---------- | ------------------------------ | | 0.90–1.00 | Automated acceptance candidate | | 0.75–0.89 | Secondary validation | | 0.50–0.74 | Human review | | Below 0.50 | Reject or quarantine | These thresholds require calibration against labeled data. ### 3.8 Extraction Output Schema ```json { "entity_id": "candidate_001", "canonical_name": "ABC-101", "entity_type": "Compound", "attributes": { "compound_category": "Experimental" }, "aliases": [], "source_id": "doc_001", "mention": { "text": "compound ABC-101", "start": 25, "end": 39 }, "confidence": 0.98, "model_version": "biomedical-ner-v1" } ``` ### 3.9 Validation Rules * Entity type must exist in ontology. * Required properties must be present. * External IDs must follow their expected format. * Confidence must be within 0–1. * Source document must exist. * Mention offsets must match source text. * Invalid candidates must not enter the canonical graph. Phase 3 Complete ### PHASE 4: RELATIONSHIP EXTRACTION ENGINE 🔗 ### 4.1 Relationship Extraction Pipeline ```text Document Text | v Entity Detection | v Entity Pair Generation | v Relation Classification | v Subject-Predicate-Object | v Context Validation | v Temporal Analysis | v Provenance Attachment | v Relationship Candidate Store ``` ### 4.2 Subject-Predicate-Object Extraction Input: "ABC-101 inhibits BACE1 and is being investigated in Alzheimer's disease models." Output: ```json [ { "subject": "ABC-101", "predicate": "TARGETS", "object": "BACE1", "confidence": 0.96 }, { "subject": "ABC-101", "predicate": "ASSOCIATED_WITH", "object": "Alzheimer's disease", "confidence": 0.89 } ] ``` The second relationship requires careful interpretation. Investigation in a disease model does not establish therapeutic efficacy. ### 4.3 Relationship Classification Categories: * Therapeutic relationships. * Biological interactions. * Research investigation relationships. * Authorship relationships. * Institutional relationships. * Experimental evidence relationships. * Temporal relationships. ### 4.4 Relationship Directionality Direction must be semantically consistent. Example: ```text (Drug)-[:TARGETS]->(Target) (Trial)-[:INVESTIGATES]->(Compound) (Publication)-[:AUTHORED_BY]->(Researcher) ``` Avoid creating reversed edges unless a specific query requirement justifies them. ### 4.5 Relationship Properties ```json { "relationship_id": "rel_001", "type": "TARGETS", "confidence": 0.96, "evidence_type": "Experimental", "evidence_text": "ABC-101 inhibits BACE1", "source_id": "doc_001", "extracted_at": "2026-11-14T00:00:00Z", "valid_from": null, "valid_to": null, "extraction_version": "relation-v1" } ``` ### 4.6 Multi-Entity Relationships Consider: "A Phase II trial evaluated compounds ABC-101 and DEF-202 in patients with Alzheimer's disease." Represent this using separate graph relationships: ```text Trial-001 | ├── INVESTIGATES → ABC-101 | ├── INVESTIGATES → DEF-202 | └── STUDIES_DISEASE → Alzheimer's disease ``` Store trial-level context such as phase and recruitment status on the trial node. ### 4.7 Contradiction Detection Example: * Publication A: Compound X demonstrated target inhibition. * Publication B: Compound X showed no significant target inhibition. Do not overwrite one finding with another. Instead: * Preserve both findings. * Attach publication provenance. * Record experimental conditions. * Record study dates. * Record population and methodology. * Mark conflicting evidence for review. ### 4.8 Relationship Acceptance Rules | Condition | Action | | ---------------------------------- | ------------------- | | Valid entities and strong evidence | Accept candidate | | Missing source | Reject | | Ambiguous direction | Human review | | Contradictory evidence | Preserve separately | | Unsupported therapeutic claim | Reject | | Unclear entity mapping | Quarantine | Phase 4 Complete ### PHASE 5: ONTOLOGY AND GRAPH SCHEMA DESIGN 🏗️ ### 5.1 Graph Schema  Primary node labels: ```text Drug Compound Disease Target ClinicalTrial Researcher Institution Publication Study Mechanism Finding SourceDocument Tenant ``` ### 5.2 Core Graph Relationships ```text Drug ──TREATS──────────> Disease Drug ──TARGETS─────────> Target Drug ──HAS_MECHANISM───> Mechanism ClinicalTrial ──INVESTIGATES──> Compound ClinicalTrial ──STUDIES_DISEASE──> Disease ClinicalTrial ──CONDUCTED_AT──> Institution Publication ──AUTHORED_BY──> Researcher Publication ──REPORTS──────> Finding Publication ──STUDIES─────> Study Finding ──ABOUT───────────> Compound Finding ──CONCERNS────────> Disease Finding ──SUPPORTED_BY────> SourceDocument ``` ### 5.3 Neo4j Node Schema Example Cypher: ```cypher CREATE CONSTRAINT drug_id_unique FOR (d:Drug) REQUIRE d.canonical_id IS UNIQUE; CREATE CONSTRAINT disease_id_unique FOR (d:Disease) REQUIRE d.canonical_id IS UNIQUE; CREATE CONSTRAINT trial_id_unique FOR (t:ClinicalTrial) REQUIRE t.canonical_id IS UNIQUE; CREATE CONSTRAINT publication_id_unique FOR (p:Publication) REQUIRE p.canonical_id IS UNIQUE; ``` ### 5.4 Index Strategy ```cypher CREATE INDEX drug_name_index FOR (d:Drug) ON (d.name); CREATE INDEX disease_name_index FOR (d:Disease) ON (d.name); CREATE INDEX publication_doi_index FOR (p:Publication) ON (p.doi); ``` Add indexes for frequently queried properties based on actual query plans. ### 5.5 Graph Property Constraints Required properties: * canonical_id * tenant_id * created_at * updated_at Entity-specific properties: * Drug: name, drug_class. * Disease: name, ontology_id. * Compound: name, chemical_identifier. * ClinicalTrial: registry_id, phase, status. * Publication: title, publication_date, DOI/PMID where available. ### 5.6 Schema Evolution Version schema changes: ```text schema_version: 1.0 ``` Evolution process: * Propose ontology modification. * Validate compatibility. * Migrate affected records. * Update extraction schemas. * Update retrieval queries. * Run regression tests. * Publish new schema version. Never remove historical properties without a migration and retention strategy. Phase 5 Complete ### PHASE 6: ENTITY RESOLUTION AND DEDUPLICATION 🧬 ### 6.1 Resolution Architecture ```text Extracted Entity | v Exact Identifier Matching | v Name Normalization | v Fuzzy Matching | v Semantic Matching | v Conflict Detection | v Resolution Decision | ├── Existing Entity ├── New Entity └── Human Review ``` ### 6.2 Matching Strategies Exact matching Use: * DOI. * PMID. * Clinical trial registry ID. * Valid ontology identifiers. * Verified chemical identifiers. Fuzzy matching Example: ```text Alzheimer Disease Alzheimer's disease Alzheimer disease ``` Use normalized text and controlled similarity thresholds. Semantic matching Use embeddings to identify possible equivalents. Important: Semantic similarity alone must never authorize automatic merging of drugs or compounds. ### 6.3 Matching Score M = 0.45I + 0.25N + 0.20A + 0.10C Where: * I = Identifier match. * N = Name similarity. * A = Attribute similarity. * C = Context similarity. ### 6.4 Resolution Decisions | Score | Decision | | ---------- | ------------------------------------ | | 0.98–1.00 | Automatic merge if identifiers agree | | 0.85–0.97 | Review or corroborate | | 0.65–0.84 | Human review | | Below 0.65 | Keep separate | A verified identifier conflict overrides a high similarity score. ### 6.5 Alias Management ```json { "canonical_id": "disease:example001", "canonical_name": "Alzheimer's disease", "aliases": [ "Alzheimer Disease", "AD" ], "alias_sources": [ "source_001", "source_002" ] } ``` ### 6.6 Merge Safety Before merging: * Verify entity categories. * Compare external identifiers. * Compare critical attributes. * Check conflicting chemical structures. * Preserve old identifiers as aliases or redirect mappings. * Maintain a reversible merge event. * Require human approval for high-impact ambiguous merges. Phase 6 Complete ### PHASE 7: DOCUMENT AND DATA INGESTION 📥 ### 7.1 Ingestion Architecture ```text PDF / HTML / CSV / JSON / API | v Source Connectors | v Ingestion Gateway | v Object Storage | v Document Parsing | v Text Extraction | v Metadata Extraction | v Chunking | v Processing Queue | v Entity + Relationship Engine | v Graph Construction ``` ### 7.2 Source Connector Design | Source | Connector | Processing | | ----------------- | ---------------- | ------------------- | | PDF | Document parser | Text and metadata | | HTML | BeautifulSoup | Content extraction | | CSV | Pandas | Structured records | | JSON | Pydantic | Schema validation | | PubMed | API connector | Publication records | | Trial registries | API connector | Trial metadata | | Institutional API | Custom connector | External records | ### 7.3 Document Metadata ```json { "document_id": "doc_001", "source_type": "research_pdf", "source_uri": "storage://research/doc_001.pdf", "tenant_id": "tenant_001", "checksum": "sha256:example", "ingested_at": "2026-11-14T00:00:00Z", "document_version": 1, "processing_status": "COMPLETED" } ``` ### 7.4 Chunking Strategy Use structure-aware chunking. Recommended document structure: * Title and abstract. * Introduction. * Methodology. * Results. * Discussion. * Conclusion. * References. Proposed initial chunk configuration: | Parameter | Starting value | | ------------------ | -------------- | | Chunk size | 800 tokens | | Overlap | 120 tokens | | Maximum chunk size | 1,200 tokens | | Metadata retention | Full | These are starting values requiring retrieval evaluation. ### 7.5 Incremental Ingestion * Detect new or modified source. * Calculate document checksum. * Compare with existing checksum. * Skip unchanged content. * Create a new document version if modified. * Reprocess affected chunks. * Re-extract affected entities and relationships. * Update graph and vector indexes. * Record processing status. ### 7.6 Failure Handling Use Celery with Redis as the initial task queue. * Retry transient failures. * Apply exponential backoff. * Send exhausted jobs to a dead-letter queue. * Preserve failed document metadata. * Support manual reprocessing. * Ensure idempotent processing. Phase 7 Complete ### PHASE 8: GRAPH DATABASE ARCHITECTURE 🗄️ ### 8.1 Database Evaluation | Database | Strength | Trade-off | | -------------- | ------------------------------------- | --------------------------------------- | | Neo4j | Rich graph queries, Cypher, ecosystem | Licensing and clustering considerations | | Amazon Neptune | Managed graph infrastructure | AWS ecosystem dependency | | ArangoDB | Multi-model storage | Different graph query ecosystem | | Memgraph | High-performance graph processing | Deployment and ecosystem considerations | ### 8.2 Recommended Selection: Neo4j Recommended for initial implementation Why: * Native graph modeling. * Cypher query language. * Relationship traversal. * Uniqueness constraints. * Mature developer ecosystem. * Suitable for knowledge graph workloads. This is a provisional recommendation based on the specified stack, not a benchmark result. ### 8.3 Storage Architecture ```text FastAPI Services | v Graph Repository Layer | v Neo4j Cluster | ├── Primary / Leader ├── Read Replicas └── Backup Storage ``` The exact cluster configuration depends on deployment edition and hosting model. ### 8.4 Graph Query Example Find compounds connected to a disease through clinical trials: ```cypher MATCH (d:Disease {name: $disease}) <-[:STUDIES_DISEASE]-(t:ClinicalTrial) -[:INVESTIGATES]->(c:Compound) RETURN DISTINCT c.canonical_id AS compound_id, c.name AS compound_name, t.canonical_id AS trial_id, t.phase AS trial_phase LIMIT 50; ``` ### 8.5 Transaction Management * Use transactions for related node and edge creation. * Enforce uniqueness constraints. * Use deterministic identifiers. * Implement retry-safe writes. * Avoid uncontrolled parallel writes to the same graph regions. ### 8.6 Scaling Strategy Initial: * Single logical graph. * Indexed entity identifiers. * Query profiling. * Read replicas where supported. * Batch ingestion. Future: * Cluster scaling. * Workload separation. * Graph partitioning only if measured bottlenecks justify it. * Tenant-aware partition strategy. ### 8.7 Backup and Recovery * Scheduled full backups. * Transaction log retention where supported. * Encrypted backup storage. * Restore validation. * Recovery point objective and recovery time objective defined by business owners. Phase 8 Complete ### PHASE 9: KNOWLEDGE GRAPH CONSTRUCTION 🏭 ### 9.1 Construction Pipeline ```text Validated Entity Candidates | v Canonical Entity Resolution | v Graph Schema Validation | v Node Transformation | v Node Upsert | v Relationship Validation | v Edge Upsert | v Provenance Attachment | v Graph Integrity Checks | v Production Knowledge Graph ``` ### 9.2 Entity-to-Node Transformation Input: ```json { "canonical_id": "compound:abc101", "name": "ABC-101", "entity_type": "Compound" } ``` Cypher: ```cypher MERGE (c:Compound { canonical_id: $canonical_id }) ON CREATE SET c.name = $name, c.created_at = datetime() ON MATCH SET c.updated_at = datetime() RETURN c; ``` ### 9.3 Relationship-to-Edge Transformation ```cypher MATCH (c:Compound { canonical_id: $compound_id }) MATCH (t:Target { canonical_id: $target_id }) MERGE (c)-[r:TARGETS { relationship_id: $relationship_id }]->(t) SET r.confidence = $confidence, r.source_id = $source_id, r.evidence_type = $evidence_type; ``` ### 9.4 Transaction Boundaries Recommended transaction unit: * One document or controlled document batch. * Entity upserts. * Relationship upserts. * Provenance writes. * Processing status update. Avoid making an entire large ingestion run one transaction. ### 9.5 Graph Integrity Checks Verify: * No orphaned required relationships. * No duplicate canonical identifiers. * No invalid relationship types. * No missing provenance. * No invalid tenant ownership. * No incompatible node categories. * No unsupported therapeutic claims. ### 9.6 Idempotency Use stable keys: ```text entity_key = canonical_id relationship_key = hash(subject_id + predicate + object_id + evidence_id) ``` This prevents duplicate creation during retries. Phase 9 Complete ### PHASE 10: DATA PROVENANCE AND VERSIONING 📚 ### 10.1 Provenance Model Every extracted fact must be traceable to: * Source document. * Source version. * Document location. * Original text. * Extraction model. * Extraction timestamp. * Confidence score. * Validation status. ### 10.2 Provenance Graph ```text SourceDocument | ├── SUPPORTS → Entity | └── SUPPORTS → Relationship Publication | └── REPORTS → Finding | ├── ABOUT → Compound └── CONCERNS → Disease ``` ### 10.3 Evidence Node ```json { "evidence_id": "evidence_001", "document_id": "doc_001", "document_version": 1, "text_span": "ABC-101 inhibits BACE1", "page_number": 5, "section": "Results", "extraction_model": "relation-v1", "confidence": 0.96 } ``` ### 10.4 Versioning Strategy Use three levels: * Document versioning. * Extraction versioning. * Graph fact versioning. A new extraction must not silently destroy older evidence. ### 10.5 Correction and Rollback When an extraction error is identified: * Identify affected fact. * Identify originating document and model version. * Mark the fact as superseded or invalidated. * Reprocess the source if needed. * Recalculate dependent indexes. * Record correction history. * Preserve the audit record. ### 10.6 Temporal Modeling Distinguish: * `valid_from`: When the fact is considered valid. * `valid_to`: When the fact stops being valid. * `recorded_at`: When the system recorded it. * `superseded_at`: When a later version replaced it. This is important for changing clinical trial status and evolving research conclusions. Phase 10 Complete ### PHASE 11: KNOWLEDGE RETRIEVAL ENGINE 🔎 ### 11.1 Retrieval Architecture The retrieval engine must support structured graph queries, semantic retrieval, and evidence-based research discovery. ```text User Query | v Query Understanding | v Intent Classification | v Entity Linking | v Retrieval Strategy Selection | ├── Exact Entity Lookup | ├── Graph Traversal | ├── Vector Search | └── Hybrid Retrieval | v Result Ranking | v Evidence Collection | v Context Assembly | v Retrieved Results ``` ### 11.2 Retrieval Methods | Method | Purpose | Example | | -------------- | ----------------------------- | ---------------------------------- | | Exact lookup | Find known entity | Find ABC-101 | | One-hop | Direct relationships | ABC-101 targets which proteins? | | Multi-hop | Discover indirect connections | Drug → Target → Disease | | Neighborhood | Explore surrounding knowledge | All connected entities | | Semantic | Understand meaning | Similar neurodegeneration research | | Temporal | Filter by dates | Trials started after 2024 | | Evidence-based | Retrieve supporting sources | Publications supporting a finding | ### 11.3 Graph Traversal Example Question: "Which publications discuss compounds investigated for Alzheimer's disease?" Cypher: ```cypher MATCH (d:Disease {name: $disease}) <-[:STUDIES_DISEASE]- (t:ClinicalTrial) -[:INVESTIGATES]-> (c:Compound) <-[:ABOUT]- (f:Finding) <-[:REPORTS]- (p:Publication) RETURN DISTINCT c.name AS compound, t.registry_id AS trial, p.title AS publication, p.doi AS doi ORDER BY publication LIMIT 50; ``` ### 11.4 Query Intent Classification | Intent | Retrieval strategy | | ---------------------- | -------------------------------- | | Entity identification | Exact lookup | | Relationship discovery | Graph traversal | | Scientific explanation | Hybrid retrieval | | Research comparison | Multi-hop + evidence | | Latest trial status | Structured current-source lookup | | Broad topic discovery | Vector search + graph expansion | ### 11.5 Result Ranking Proposed ranking formula: R = 0.35S + 0.25E + 0.20G + 0.10F + 0.10T Where: * S = Semantic relevance. * E = Evidence quality. * G = Graph relevance. * F = Source freshness. * T = Entity and relationship confidence. The formula is a starting hypothesis. Weights should be optimized using labeled retrieval judgments. ### 11.6 Context Assembly Each retrieved result should include: ```json { "entity": "ABC-101", "relationship": "INVESTIGATES", "connected_entity": "Clinical Trial 001", "confidence": 0.94, "evidence": { "document_id": "doc_001", "page": 5, "section": "Results" }, "source_type": "research_publication" } ``` ### 11.7 Retrieval Optimization * Apply indexed entity lookup first. * Limit uncontrolled traversal depth. * Use parameterized Cypher queries. * Filter by tenant before returning results. * Apply query timeouts. * Use caching for frequent entity lookups. * Avoid retrieving entire graph neighborhoods. Phase 11 Complete ### PHASE 12: GRAPHRAG INTEGRATION 🧠 ### 12.1 GraphRAG Architecture GraphRAG combines structured graph relationships with relevant scientific document evidence.  ```text User Question | v Query Understanding | v Entity Linking | v Retrieval Planner | +--------+--------+ | | v v Neo4j Qdrant Graph Search Vector Search | | +--------+--------+ | v Result Aggregation | v Evidence Ranking | v Context Assembly | v GPT API | v Answer Validation | v Evidence-Cited Answer ``` ### 12.2 Query Processing Input: "Explain the relationship between BACE1, experimental compounds, and Alzheimer's disease research." Processing: * Detect research explanation intent. * Extract BACE1 as Target. * Resolve Alzheimer's disease as Disease. * Identify related Compound entities. * Retrieve associated clinical trials. * Search publications semantically. * Collect supporting and contradictory evidence. * Build a relevant subgraph. * Generate a grounded answer. ### 12.3 Graph Query Generation The query planner should use predefined query templates rather than allowing unrestricted LLM-generated database queries. Example: ```cypher MATCH (target:Target {name: $target}) <-[:TARGETS]- (compound:Compound) -[:ASSOCIATED_WITH]-> (disease:Disease {name: $disease}) RETURN compound.name, target.name, disease.name LIMIT 30; ``` Only execute a template after validating entity identifiers, permissions, and query parameters. ### 12.4 Context Selection Prioritize: * Directly connected entities. * Strongly supported relationships. * Primary research publications. * Relevant clinical trial evidence. * Recent evidence where recency matters. * Contradictory findings. ### 12.5 LLM Answer Generation The LLM receives: * Original question. * Relevant graph relationships. * Source passages. * Evidence metadata. * Confidence information. * Contradictory findings. * Tenant access restrictions. System-level answer rules: * Never invent a clinical trial. * Never convert association into causation. * Never claim efficacy from preclinical evidence. * Cite supporting sources. * Distinguish established findings from hypotheses. * Report insufficient evidence when appropriate. ### 12.6 Example Output Contract ```json { "answer": "The retrieved evidence indicates...", "entities": [ { "name": "BACE1", "type": "Target" } ], "relationships": [], "citations": [ { "document_id": "doc_001", "page": 5, "section": "Results" } ], "evidence_quality": "REQUIRES_REVIEW", "limitations": [] } ``` This is an illustrative response structure, not an actual scientific conclusion. ### 12.7 GraphRAG Evaluation Measure: * Retrieval precision. * Retrieval recall. * Citation correctness. * Answer faithfulness. * Relationship accuracy. * Unsupported claim rate. * Multi-hop reasoning accuracy. Phase 12 Complete ### PHASE 13: GRAPH AND VECTOR INTEGRATION 🔄 ### 13.1 Why Hybrid Architecture? Graph databases are optimized for explicit relationships. Vector databases are optimized for semantic similarity. They solve different retrieval problems. | Requirement | Graph | Vector | | ---------------------------- | ----------------- | --------------------------- | | Exact entity matching | Excellent | Not ideal | | Multi-hop relationships | Excellent | Not suitable alone | | Semantic similarity | Limited | Excellent | | Scientific passage retrieval | Limited | Excellent | | Relationship explanations | Excellent | Requires additional context | | Source passage discovery | Requires modeling | Excellent | ### 13.2 Proposed Architecture FastAPI Retrieval Gateway Neo4j Entities and relationships Qdrant Document embeddings Hybrid Ranking and Context Fusion ### 13.3 Embedding Strategy Generate embeddings for: * Publication abstracts. * Document chunks. * Research findings. * Compound descriptions. * Disease descriptions. * Relevant ontology definitions. Store embeddings in Qdrant. ### 13.4 Vector Record Schema ```json { "id": "chunk_001", "vector": [], "payload": { "document_id": "doc_001", "tenant_id": "tenant_001", "entity_ids": [ "compound:abc101", "target:bace1" ], "section": "Results", "page": 5, "embedding_version": "embedding-v1" } } ``` ### 13.5 Hybrid Retrieval Workflow * Convert user query into an embedding. * Retrieve semantically relevant document chunks. * Extract linked entity identifiers. * Find matching canonical graph nodes. * Traverse connected graph relationships. * Combine graph and vector results. * Apply tenant filtering. * Rank the evidence. * Return source-linked context. ### 13.6 Synchronization Neo4j and Qdrant should not rely on a distributed transaction. Use an event-driven synchronization approach: ```text Graph Transaction | v Transactional Outbox | v Background Worker | v Embedding Generation | v Qdrant Upsert | v Sync Status Update ``` ### 13.7 Embedding Version Management Maintain: * Model name. * Model version. * Embedding dimension. * Chunking version. * Creation timestamp. * Source document version. When changing embedding models: * Create a new vector collection. * Generate new embeddings. * Evaluate retrieval. * Switch traffic. * Retain rollback capability. ### 13.8 When Vector Storage Is Unnecessary Do not introduce Qdrant if the application only requires: * Exact entity lookup. * Structured graph queries. * Known relationship traversal. * Deterministic graph analytics. For this project, vector storage is justified by the requirement for scientific semantic retrieval. Phase 13 Complete ### PHASE 14: BACKEND API ARCHITECTURE ⚙️ ### 14.1 Service Architecture ```text API Gateway | v Authentication Middleware | v FastAPI Application | ├── Entity Service ├── Relationship Service ├── Ingestion Service ├── Graph Query Service ├── Search Service ├── Retrieval Service └── Analytics Service | v Repository Layer | +-----+------+ | | v v Neo4j Qdrant ``` ### 14.2 API Endpoint Specification | Method | Endpoint | Purpose | | ------ | ------------------------------- | ---------------------------- | | POST | /api/v1/entities | Create entity | | GET | /api/v1/entities/{id} | Retrieve entity | | PATCH | /api/v1/entities/{id} | Update entity | | GET | /api/v1/entities/{id}/neighbors | Retrieve neighbors | | POST | /api/v1/relationships | Create relationship | | GET | /api/v1/relationships/{id} | Retrieve relationship | | POST | /api/v1/ingestion/jobs | Start ingestion | | GET | /api/v1/ingestion/jobs/{id} | Job status | | POST | /api/v1/graph/query | Execute approved graph query | | POST | /api/v1/search | Semantic search | | POST | /api/v1/retrieval/query | Hybrid retrieval | | POST | /api/v1/graphrag/ask | GraphRAG question | | GET | /api/v1/analytics/overview | Graph analytics | ### 14.3 Entity Creation Contract Request: ```json { "entity_type": "Compound", "canonical_id": "compound:abc101", "name": "ABC-101", "attributes": { "compound_category": "Experimental" } } ``` Response: ```json { "entity_id": "compound:abc101", "status": "CREATED", "schema_version": "1.0" } ``` ### 14.4 Graph Query Contract Request: ```json { "query_type": "disease_compound_trials", "parameters": { "disease_id": "disease:example001" }, "limit": 25 } ``` Response: ```json { "results": [], "count": 0, "execution_time_ms": 0, "next_cursor": null } ``` The empty result is a schema illustration, not a claim about the actual database. ### 14.5 GraphRAG API Contract Request: ```json { "question": "Which compounds are investigated for Alzheimer's disease?", "retrieval_mode": "hybrid", "max_graph_hops": 3, "top_k": 10, "include_citations": true } ``` Response: ```json { "request_id": "req_001", "answer": "Generated evidence-based response", "citations": [], "retrieved_entities": [], "retrieval_metadata": { "graph_results": 0, "vector_results": 0 } } ``` ### 14.6 Error Handling Standard response: ```json { "error": { "code": "ENTITY_NOT_FOUND", "message": "The requested entity does not exist.", "request_id": "req_001" } } ``` HTTP status codes: | Status | Meaning | | ------ | ---------------------- | | 200 | Successful retrieval | | 201 | Resource created | | 202 | Processing accepted | | 400 | Invalid request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not found | | 409 | Conflict | | 422 | Validation failure | | 429 | Rate limited | | 500 | Internal error | | 503 | Dependency unavailable | ### 14.7 API Security * OAuth2/OIDC authentication. * JWT validation. * Tenant-aware authorization. * Request schema validation. * Rate limiting. * Request size restrictions. * Parameterized Cypher. * API audit logs. * Sensitive information redaction. Phase 14 Complete ### PHASE 15: DATA QUALITY AND CONSISTENCY 🛡️ ### 15.1 Quality Framework Four validation layers: * Source validation. * Entity validation. * Relationship validation. * Graph integrity validation. ### 15.2 Entity Validation Rules | Rule | Validation | | ----- | ----------------------------------- | | E-001 | Canonical ID must be unique | | E-002 | Entity type must exist | | E-003 | Required name must be present | | E-004 | External identifier must be valid | | E-005 | Tenant ID must exist | | E-006 | Source provenance must be available | ### 15.3 Relationship Validation Example: ```text Drug → TARGETS → Target ``` Allowed. ```text Researcher → TARGETS → Disease ``` Invalid under the defined ontology unless an explicit new relationship type is introduced. ### 15.4 Contradiction Detection Create a contradiction detection service. Check: * Conflicting experimental results. * Different clinical trial statuses. * Conflicting entity attributes. * Duplicate but inconsistent records. * Invalid temporal sequences. Contradictory scientific findings should remain separately represented with evidence. ### 15.5 Data Quality Metrics | Metric | Definition | | --------------------- | ----------------------------------------- | | Entity validity | Valid entities / total entities | | Relationship validity | Valid relationships / total relationships | | Duplicate rate | Duplicate candidates / total candidates | | Provenance coverage | Facts with sources / total facts | | Extraction precision | Correct extracted items / extracted items | | Extraction recall | Correct extracted items / actual items | ### 15.6 Human Review Queue Review categories: * Ambiguous drug identity. * Uncertain compound-target relationship. * Conflicting trial information. * Low-confidence extraction. * Missing source evidence. * Potentially incorrect therapeutic association. Every reviewer decision should be auditable. ### 15.7 Consistency Strategy Use: * Database uniqueness constraints. * Transactional graph writes. * Idempotent ingestion. * Outbox-based synchronization. * Periodic graph integrity checks. * Versioned corrections. Phase 15 Complete ### PHASE 16: SECURITY AND ACCESS CONTROL 🔐 ### 16.1 Security Architecture ```text Enterprise User | v Identity Provider | v API Gateway | v JWT Authentication | v Authorization Engine | v Tenant Policy Enforcement | v Backend Services | v Database Access Layer ``` ### 16.2 Role-Based Access Control | Role | Permissions | | ------------- | ---------------------------------------- | | Super Admin | Platform administration | | Tenant Admin | Tenant configuration | | Researcher | Search and retrieve authorized knowledge | | Data Engineer | Ingestion and validation | | Reviewer | Review extraction candidates | | Read Only | Read authorized graph information | ### 16.3 Tenant Isolation Every tenant-owned record must contain: ```json { "tenant_id": "tenant_001" } ``` Important implementation rules: * Derive tenant identity from verified authentication claims. * Never trust tenant IDs supplied directly by users. * Apply tenant filters to graph and vector queries. * Ensure every traversal remains within authorized boundaries. * Test indirect cross-tenant data leakage. For shared public research knowledge, distinguish globally reusable verified facts from tenant-specific private data. Use explicit ownership and access policies rather than assuming all graph records are private or public. ### 16.4 Encryption * TLS for network communication. * Encryption at rest. * Managed encryption keys. * Secure credential storage. * Secret rotation. * Encrypted backup storage. ### 16.5 Audit Logging Log: * User identity. * Tenant ID. * Request ID. * Operation. * Accessed entity IDs. * Timestamp. * Authorization outcome. * Administrative modifications. Do not unnecessarily log sensitive document contents or access tokens. ### 16.6 Security Threat Model | Threat | Mitigation | | -------------------------------------- | -------------------------------------- | | Cross-tenant data leakage | Mandatory tenant enforcement | | Cypher injection | Parameterized queries | | Unauthorized graph modification | RBAC | | Token theft | Short-lived tokens and secure rotation | | Prompt injection in research documents | Treat source text as untrusted data | | Data exfiltration | Access policies and audit logs | | Malicious ingestion file | File validation and sandboxed parsing | | Excessive graph traversal | Query limits and timeouts | ### 16.7 Data Retention Define retention policies for: * Raw documents. * Extracted text. * Embeddings. * Graph records. * Audit events. * Deleted tenant data. Deletion workflows must also remove or appropriately isolate dependent vector records, caches, and derived data. Phase 16 Complete ### PHASE 17: PERFORMANCE AND SCALABILITY 🚀 ### 17.1 Capacity Planning Proposed initial workload: | Parameter | Target | | ------------------------ | ----------------------- | | Graph entities | 5 million | | Graph relationships | 20 million | | Concurrent users | 500 | | Common retrieval latency | Under 2 seconds | | Graph traversal depth | Up to 3 hops by default | | Ingestion | Incremental | | Initial document corpus | 100,000 | ### 17.2 Performance Bottlenecks | Component | Possible bottleneck | Solution | | ----------------- | --------------------- | -------------------------------- | | Document parsing | Large PDF processing | Distributed workers | | Entity extraction | Model inference | Batch inference | | Neo4j | Expensive traversals | Indexes and query profiling | | Qdrant | Large vector searches | Payload indexes and filtering | | FastAPI | Concurrent requests | Async I/O and controlled pools | | LLM | Generation latency | Context optimization and caching | | Redis | Cache pressure | TTL and eviction policies | ### 17.3 Query Optimization Example inefficient pattern: ```cypher MATCH (n) OPTIONAL MATCH (n)-[r]-(m) RETURN n, r, m; ``` This may retrieve an unnecessarily large portion of the graph. Improved pattern: ```cypher MATCH (d:Disease { canonical_id: $disease_id }) MATCH (d)<-[:STUDIES_DISEASE]-(t:ClinicalTrial) -[:INVESTIGATES]->(c:Compound) RETURN DISTINCT c.name, t.registry_id LIMIT 50; ``` ### 17.4 Caching Strategy Use Redis for: * Frequent entity lookups. * Common query results. * Ontology metadata. * Frequently accessed public knowledge. * Temporary retrieval state. Cache keys must include tenant scope and relevant graph or index version. ### 17.5 Horizontal Scaling Potential scaling approach: ```text Load Balancer | FastAPI Instances / | \ v v v Worker Worker Worker \ | / Processing Queue | Storage Layer / \ Neo4j Qdrant ``` ### 17.6 Performance Targets Proposed targets, subject to workload testing: | Operation | Initial target | | ------------------------ | ------------------------------------------------------------------- | | Exact entity lookup | P95 under 200 ms | | Simple graph query | P95 under 500 ms | | Hybrid retrieval | P95 under 1.5 seconds | | Common GraphRAG response | P95 under 2 seconds only if generation and retrieval budgets permit | LLM generation can exceed these limits. Therefore, the two-second project requirement should be treated as a retrieval-focused SLO until realistic end-to-end benchmarks confirm otherwise. ### 17.7 Capacity Optimization * Benchmark representative graph shapes. * Profile expensive queries. * Control traversal depth. * Use pagination. * Batch ingestion. * Separate interactive and background workloads. * Monitor memory and CPU utilization. * Scale only after bottlenecks are measured. Phase 17 Complete ### PHASE 18: OBSERVABILITY AND MONITORING 📊 ### 18.1 Monitoring Architecture ```text FastAPI + Workers + Databases | v OpenTelemetry | +------+------+ | | | v v v Metrics Logs Traces | | | +------+------+ | v Monitoring Platform | v Alert Manager ``` ### 18.2 Recommended Tools | Tool | Purpose | | ---------------- | --------------------- | | Prometheus | Metrics | | Grafana | Dashboards | | OpenTelemetry | Distributed tracing | | Loki | Log aggregation | | Sentry | Application errors | | Neo4j monitoring | Graph database health | ### 18.3 Pipeline Metrics Track: * Documents received. * Documents processed. * Failed ingestion jobs. * Extraction throughput. * Extraction confidence distribution. * Entity resolution success rate. * Graph write failures. * Vector synchronization lag. ### 18.4 Retrieval Metrics Track: * Query count. * Query latency. * Graph traversal depth. * Vector search latency. * Retrieval relevance. * Empty result rate. * Citation coverage. * GraphRAG answer generation latency. ### 18.5 Operational Alerts | Condition | Alert | | ----------------------------------- | -------- | | Ingestion failures exceed threshold | Critical | | Database unavailable | Critical | | Vector synchronization delayed | Warning | | API P95 exceeds SLO | Warning | | Tenant authorization failures spike | Security | | Graph integrity failure | Critical | ### 18.6 Dashboard Design Recommended dashboards: * Ingestion operations. * Extraction quality. * Graph database performance. * Vector database performance. * Retrieval quality. * Security and audit events. * Infrastructure resource utilization. Phase 18 Complete ### PHASE 19: TESTING AND EVALUATION 🧪 ### 19.1 Testing Architecture ```text Unit Tests | v Integration Tests | v Schema Tests | v Pipeline Tests | v Retrieval Evaluation | v Security Tests | v Load Tests | v Production Readiness Review ``` ### 19.2 Entity Extraction Tests Test cases: | Test ID | Input | Expected | | ------- | ---------------------- | ----------------------------- | | ENT-001 | Known drug name | Drug candidate | | ENT-002 | Disease alias | Normalized disease | | ENT-003 | Ambiguous acronym | Contextual disambiguation | | ENT-004 | Unknown compound | Candidate with no invented ID | | ENT-005 | Missing entity context | Review or rejection | ### 19.3 Relationship Extraction Tests | Test ID | Scenario | Expected | | ------- | --------------------------- | ----------------------- | | REL-001 | Explicit target inhibition | TARGETS candidate | | REL-002 | Trial investigates compound | INVESTIGATES | | REL-003 | Negated treatment statement | No positive TREATS edge | | REL-004 | Speculative relationship | Uncertainty preserved | | REL-005 | Contradictory findings | Both findings retained | ### 19.4 Entity Resolution Tests * Exact identifier match. * Alias matching. * Similar names with different chemical identifiers. * Duplicate publication. * Conflicting ontology identifiers. * Ambiguous acronym. * Merge rollback. ### 19.5 Graph Integrity Tests * Unique node identifiers. * Valid edge directions. * Required relationship properties. * Valid provenance. * No unauthorized cross-tenant traversal. * Consistent entity references. ### 19.6 API Tests Validate: * Correct HTTP response codes. * Request schema validation. * Authentication. * Authorization. * Pagination. * Rate limiting. * Invalid identifiers. * Database failure handling. ### 19.7 GraphRAG Evaluation Use a human-reviewed gold dataset. | Metric | Purpose | | ------------------ | ----------------------------------- | | Recall@K | Relevant evidence coverage | | Precision@K | Relevance of retrieved results | | MRR | Ranking quality | | NDCG@K | Ranking effectiveness | | Faithfulness | Grounding in retrieved evidence | | Citation precision | Citation support accuracy | | Citation recall | Coverage of claims needing evidence | | Answer relevance | Question-answer alignment | ### 19.8 Performance Testing Test: * 50 concurrent users. * 100 concurrent users. * 250 concurrent users. * 500 concurrent users. These are proposed test scenarios, not completed load tests. Measure: * P50 latency. * P95 latency. * P99 latency. * Requests per second. * Error rate. * Database connection saturation. * CPU and memory usage. ### 19.9 Security Testing * Tenant boundary testing. * Cypher injection attempts. * Prompt injection testing. * Authentication bypass. * Unauthorized entity updates. * Sensitive data leakage. * File parsing vulnerabilities. ### 19.10 Acceptance Criteria The project should not move to production until: * Critical extraction tests pass. * Graph integrity checks pass. * Tenant isolation tests pass. * Provenance coverage meets its defined target. * Retrieval evaluation meets agreed relevance thresholds. * Load tests meet approved SLOs. * Backup restoration is verified. Phase 19 Complete ### PHASE 20: DEPLOYMENT AND INFRASTRUCTURE ☁️ ### 20.1 Deployment Architecture Recommended initial deployment: ```text Internet | v Load Balancer | v API Gateway | v FastAPI Service | +------------+------------+ | | | v v v Neo4j Qdrant Redis | v Graph Storage Background Processing: | v Celery Workers | v Redis Queue | v Object Storage Monitoring: Prometheus + Grafana + OpenTelemetry ``` ### 20.2 Containerization Services: | Container | Responsibility | | ----------------- | -------------------- | | api | FastAPI | | ingestion-worker | Document processing | | extraction-worker | Entity extraction | | graph-worker | Graph writes | | embedding-worker | Embedding generation | | neo4j | Graph storage | | qdrant | Vector storage | | redis | Queue and cache | | postgres | Operational metadata | ### 20.3 Environment Configuration ```env APP_ENV=production NEO4J_URI=bolt://neo4j:7687 NEO4J_DATABASE=neo4j QDRANT_URL=http://qdrant:6333 REDIS_URL=redis://redis:6379/0 POSTGRES_HOST=postgres POSTGRES_DB=knowledge_graph LLM_MODEL=<configured-model> EMBEDDING_MODEL=<configured-model> ``` Secrets must be injected through a secret manager, not committed to source control. ### 20.4 CI/CD Pipeline ```text Developer Commit | v Code Review | v Automated Tests | v Security Scanning | v Build Containers | v Staging Deployment | v Integration Tests | v Approval | v Production Deployment | v Health Verification ``` ### 20.5 Deployment Environments * Development: Local Docker environment. * Staging: Production-like infrastructure. * Production: High-availability deployment. ### 20.6 Backup and Disaster Recovery Proposed policy: * Daily full backups. * More frequent incremental recovery points where supported. * Encrypted off-site backup storage. * Regular restore testing. * Documented recovery runbooks. * Separate retention policies for raw documents and derived graph data. RPO and RTO must be approved by business stakeholders. Phase 20 Complete ### PHASE 21: IMPLEMENTATION ROADMAP 🗺️ ### Development Plan Illustrative 20-week plan. Actual duration depends on team size, data availability, and integration complexity. * Stage 1 – Domain Modeling and Requirements Weeks 1–2 * Confirm research requirements. * Define entity taxonomy. * Define relationship ontology. * Create source inventory. Deliverable: Approved domain model. Acceptance: Domain owners approve entity and relationship definitions. * Stage 2 – Entity and Relationship Extraction Weeks 3–4 * Configure biomedical NER. * Build structured extraction pipeline. * Implement relationship extraction. * Create labeled evaluation dataset. Deliverable: Extraction engine. Acceptance: Meets agreed extraction precision and recall. * Stage 3 – Ontology and Schema Week 5 * Implement graph node labels. * Define relationship constraints. * Create identifier standards. * Implement schema validation. Deliverable: Versioned graph schema. Acceptance: Valid test records pass schema validation. * Stage 4 – Graph Database Weeks 6–7 * Deploy Neo4j. * Create indexes. * Implement repository layer. * Build graph query templates. Deliverable: Graph storage service. Acceptance: Core entity and relationship queries work. * Stage 5 – Knowledge Ingestion Weeks 8–9 * Implement PDF and HTML connectors. * Add CSV and JSON ingestion. * Configure document parsing. * Implement chunking and queues. Deliverable: Ingestion pipeline. Acceptance: Test corpus processes with traceable job status. * Stage 6 – Entity Resolution and Graph Construction Weeks 10–11 * Build matching engine. * Implement deduplication. * Create graph upsert logic. * Add provenance tracking. Deliverable: Validated graph construction pipeline. Acceptance: Duplicate and rollback tests pass. * Stage 7 – Retrieval APIs Weeks 12–13 * Build entity APIs. * Build relationship APIs. * Implement graph traversal. * Add search endpoints. Deliverable: Retrieval backend. Acceptance: Representative queries return correct evidence. * Stage 8 – GraphRAG Integration Weeks 14–15 * Add Qdrant. * Generate embeddings. * Build hybrid retrieval. * Integrate GPT API. * Implement citations. Deliverable: GraphRAG service. Acceptance: Answers are grounded in retrieved evidence. * Stage 9 – Security and Observability Weeks 16–17 * Implement tenant isolation. * Add RBAC. * Configure audit logging. * Deploy monitoring. Deliverable: Secure operational backend. Acceptance: Tenant isolation and authorization tests pass. * Stage 10 – Testing and Production Deployment Weeks 18–20 * Run load tests. * Evaluate retrieval quality. * Verify backup restoration. * Deploy staging and production. * Conduct architecture review. Deliverable: Production-ready release candidate. Acceptance: Approved security, reliability, and performance gates pass. ### 21.2 Dependencies | Stage | Dependency | | ----- | -------------------------------------- | | 1 | Research domain experts | | 2 | Representative labeled documents | | 3 | Entity and relation definitions | | 4 | Approved schema | | 5 | Source connector access | | 6 | Extraction output | | 7 | Populated graph | | 8 | Graph and vector infrastructure | | 9 | Authentication and tenant requirements | | 10 | Completed integration and evaluation | ### 21.3 Major Project Risks * Unavailable source APIs. * Inconsistent pharmaceutical terminology. * Expensive LLM inference. * Low-quality extracted relationships. * Duplicate scientific records. * Graph query performance bottlenecks. * Cross-tenant information leakage. ### 21.4 Engineering Team Suggested initial team: | Role | Responsibility | | ------------------------- | ------------------------------ | | Knowledge Graph Architect | Domain and ontology | | Backend Engineer | FastAPI and services | | Graph Database Engineer | Neo4j | | ML/NLP Engineer | Entity and relation extraction | | Data Engineer | Ingestion and pipelines | | AI Engineer | GraphRAG and LLM | | DevOps Engineer | Infrastructure | | QA Engineer | Testing and validation | | Domain Expert | Biomedical evidence review | Phase 21 Complete ### PHASE 22: FINAL ARCHITECTURE AUDIT 🔍 ### 22.1 Architecture Review The proposed architecture is reviewed across the complete knowledge engineering lifecycle. | Architecture area | Review result | Observation | | ----------------------- | ------------- | -------------------------- | | Domain modeling | | Core entities identified | | Entity extraction | | NER and normalization | | Relationship extraction | | Direction and evidence | | Ontology | | Node and edge definitions | | Entity resolution | | Matching and merging | | Ingestion | | Multiple source formats | | Graph database | | Neo4j | | Graph construction | | Transactional upserts | | Provenance | | Evidence traceability | | Retrieval | | Multi-hop retrieval | | GraphRAG | | Evidence-grounded answers | | Vector integration | | Qdrant | | Backend APIs | | FastAPI | | Data quality | | Validation and review | | Security | | RBAC and tenant isolation | | Scalability | | Capacity strategy | | Monitoring | | Metrics and tracing | | Testing | | Multi-layer testing | | Deployment | | Containerized architecture | ### 22.2 Architectural Weaknesses The following issues require additional engineering decisions. Issue 1: Ontology complexity Pharmaceutical terminology is extensive. Risk: * Multiple identifiers for the same concept. * Conflicting terminology. * Incorrect entity classification. Recommendation: * Integrate validated biomedical ontologies. * Establish ontology governance. * Version terminology mappings. Issue 2: Evidence interpretation An experimental association must not automatically become a therapeutic relationship. Recommendation: * Separate experimental evidence from clinical evidence. * Preserve evidence type. * Introduce expert review for important therapeutic claims. Issue 3: Distributed consistency Neo4j and Qdrant do not share a normal atomic transaction. Recommendation: * Use transactional outbox. * Implement retry-safe synchronization. * Monitor vector indexing lag. * Provide reconciliation jobs. Issue 4: Graph growth A large research corpus may produce highly connected nodes. Recommendation: * Use query-specific traversal templates. * Set maximum traversal depth. * Apply pagination. * Profile expensive queries. Issue 5: Tenant isolation Shared biomedical knowledge and private research documents require different access policies. Recommendation: * Separate public canonical knowledge from private tenant-owned research. * Enforce access control at every retrieval layer. * Test indirect cross-tenant traversal. ### 22.3 Unresolved Architectural Decisions | Decision | Required approval | | --------------------------------- | --------------------- | | Biomedical ontology selection | Domain architect | | Public vs private knowledge model | Security architect | | Neo4j hosting and edition | Infrastructure team | | Embedding model | AI engineering team | | Clinical evidence classification | Biomedical experts | | Retention and deletion policies | Compliance team | | RPO and RTO | Business stakeholders | | Extraction acceptance thresholds | Research experts | ### 22.4 Final Security Audit Checklist * JWT authentication. * Tenant-aware RBAC. * Parameterized Cypher queries. * Encrypted database connections. * Secret management. * Audit logging. * Secure document parsing. * Vector metadata filtering. * Prompt injection protection. * Backup encryption. * Data deletion propagation. * Cross-tenant penetration testing. ### 22.5 Final Production Readiness Checklist * Ontology approved. * Extraction pipeline validated. * Entity resolution validated. * Relationship evidence validated. * Graph schema deployed. * Ingestion pipeline tested. * Provenance implemented. * Graph queries optimized. * Vector synchronization implemented. * GraphRAG citations validated. * APIs secured. * Tenant isolation tested. * Monitoring configured. * Backup restoration tested. * Load testing completed. * Disaster recovery documented. ### 22.6 Final Architecture Decision Recommended technology architecture | Layer | Selected technology | | -------------------- | ----------------------- | | Backend | Python + FastAPI | | Graph database | Neo4j | | Vector database | Qdrant | | Operational database | PostgreSQL | | Cache and queue | Redis | | Background workers | Celery | | Entity extraction | SciSpaCy + Transformers | | LLM | GPT API | | Document storage | Object storage | | Monitoring | Prometheus + Grafana | | Tracing | OpenTelemetry | | Deployment | Docker | Architecture recommendation: Proceed with a modular, evidence-centric GraphRAG backend. Begin with a representative research corpus and validate extraction quality and retrieval performance before scaling to the full target dataset. Phase 22 Complete ### PHASE 23: FINAL KNOWLEDGE GRAPH ARCHITECTURE AUDIT 🏆 ### 23.1 End-to-End Architecture Verification The complete data lifecycle is: ```text RESEARCH SOURCES | v DOCUMENT INGESTION | v DOCUMENT PROCESSING | v ENTITY EXTRACTION | v RELATIONSHIP EXTRACTION | v ENTITY RESOLUTION | v ONTOLOGY VALIDATION | v GRAPH CONSTRUCTION | v PROVENANCE MANAGEMENT | +------------------+ | | v v NEO4J QDRANT Graph Storage Vector Storage | | +--------+---------+ | v HYBRID RETRIEVAL | v GRAPHRAG | v EVIDENCE VALIDATION | v ANSWER GENERATION | v SOURCE-ATTRIBUTED API | v ENTERPRISE APPLICATION ``` ### 23.2 Critical Architecture Questions | Audit question | Design response | | ----------------------------------------- | ------------------------------------------ | | Can every entity be traced to its source? | Yes, through provenance records | | Can relationships retain evidence? | Yes, through evidence-linked records | | Can duplicate entities be detected? | Yes, through resolution pipeline | | Can contradictory research coexist? | Yes, through independent evidence records | | Can multi-hop retrieval be performed? | Yes, through Neo4j traversal | | Can semantic document search work? | Yes, through Qdrant | | Can GraphRAG provide citations? | Yes, through evidence assembly | | Can tenant access be isolated? | Designed through authorization enforcement | | Can ingestion recover from failure? | Yes, through idempotent jobs and retries | | Can the graph be incrementally updated? | Yes, through versioned ingestion | | Can historical knowledge be audited? | Yes, through provenance and versioning | ### 23.3 Remaining Risks Requires further validation * Actual biomedical extraction accuracy is not yet measured. * The proposed graph size has not been benchmarked. * The two-second end-to-end latency target is not guaranteed. * Ontology licensing and integration need verification. * LLM-generated relationship accuracy needs human evaluation. * Neo4j and Qdrant synchronization needs failure testing. * Tenant isolation requires penetration testing. * Real-world research evidence needs domain expert validation. ### 23.4 Final Engineering Verdict Architecture blueprint completed The PharmaKnowledge Graph project has a defined architecture covering: * 10 core domain entity categories. * 10 initial relationship categories. * Biomedical entity and relationship extraction. * Entity resolution and deduplication. * Multi-format document ingestion. * Neo4j graph storage. * Qdrant vector retrieval. * Evidence-based GraphRAG. * FastAPI backend contracts. * Provenance and versioning. * Enterprise security. * Performance and scalability planning. * Observability and monitoring. * Testing and evaluation. * Containerized deployment. * 20-week proposed implementation roadmap. Important implementation distinction: This is a complete proposed engineering blueprint, not an implemented or tested production system. Actual readiness must be established through code implementation, integration testing, security validation, and performance benchmarking. ### Final Sample Test Result Architecture phases 23 / 23 covered Project inputs 5 / 5 supplied Technical diagrams Included JSON and Cypher examples Included API contracts Included Security and scalability Covered Implementation roadmap 20 weeks proposed Sample test successfully completed at the architecture-design level. Overall assessment: The master prompt successfully produces a structured, technically detailed knowledge graph architecture for a complex enterprise pharmaceutical research use case. Its strongest areas are domain modeling, evidence provenance, entity resolution, graph construction, and hybrid GraphRAG retrieval. The next improvement would be to require concrete implementation artifacts such as executable Python modules, Pydantic models, complete Neo4j migrations, and automated test code when the user explicitly requests implementation rather than architecture design.