{"id":31144092,"url":"https://github.com/kpernyer/living-twin-monorep","last_synced_at":"2026-04-09T17:38:49.972Z","repository":{"id":311065618,"uuid":"1037042460","full_name":"kpernyer/living-twin-monorep","owner":"kpernyer","description":"🧠 Your organization's digital twin that learns, remembers, and evolves. RAG-powered knowledge system that turns scattered information into intelligent conversations.","archived":false,"fork":false,"pushed_at":"2025-09-12T12:52:05.000Z","size":24484,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-12T14:58:15.227Z","etag":null,"topics":["ai","fastapi","flutter","knowledge-graph","multi-tenant","neo4j","organzational-intelligence","rag","react","vector-search"],"latest_commit_sha":null,"homepage":"https://www.aprio.one","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kpernyer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-13T01:27:33.000Z","updated_at":"2025-09-12T12:52:09.000Z","dependencies_parsed_at":null,"dependency_job_id":"e8cf50f8-630f-4dbb-aed1-963de24166b2","html_url":"https://github.com/kpernyer/living-twin-monorep","commit_stats":null,"previous_names":["kpernyer/living-twin-monorep"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kpernyer/living-twin-monorep","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpernyer%2Fliving-twin-monorep","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpernyer%2Fliving-twin-monorep/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpernyer%2Fliving-twin-monorep/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpernyer%2Fliving-twin-monorep/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kpernyer","download_url":"https://codeload.github.com/kpernyer/living-twin-monorep/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpernyer%2Fliving-twin-monorep/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275781194,"owners_count":25527351,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-18T02:00:09.552Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","fastapi","flutter","knowledge-graph","multi-tenant","neo4j","organzational-intelligence","rag","react","vector-search"],"created_at":"2025-09-18T14:11:19.471Z","updated_at":"2025-09-18T14:11:21.245Z","avatar_url":"https://github.com/kpernyer.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Living Twin — Web Platform Development Guide\n\nThis is the development stack for **Living Twin** — a RAG-enabled, Neo4j-backed, multi-tenant \"organizational twin\" web platform.\n\n## 📜 System Architecture\n\n![System Architecture](https://www.plantuml.com/plantuml/proxy?cache=no\u0026src=https://raw.githubusercontent.com/kpernyer/living-twin-monorep/main/docs/v0.1/system/system_architecture.puml)\n\n### Microservices Architecture\n\n- **API Services**: FastAPI + Strawberry GraphQL backend with strategic intelligence\n- **Web Applications**: React + TypeScript admin interface with real-time updates\n- **Infrastructure**: GCP Cloud Run, Firebase, Neo4j graph database + vector search\n- **External Services**: OpenAI GPT-4o-mini, Firebase Auth, Sentry monitoring\n\n📋 [**View Detailed Documentation**](docs/v0.1/README.md) | 🔍 [**System Analysis**](docs/v0.1/system/SYSTEM.md) | 📚 [**Complete Docs Index**](DOCUMENTATION.md)\n\n## 📚 Documentation \u0026 Guides\n\n\u003e 🚀 **Start Here:** [**Complete Documentation Index**](DOCUMENTATION.md) - Your gateway to 61+ organized guides, tutorials, and references\n\n### **Quick Navigation:**\n- **[Getting Started](docs/getting-started/)** - New user onboarding and setup guides\n- **[API Documentation](docs/api/)** - REST API, GraphQL, and PubSub event guides\n- **[AI/ML Implementation](docs/ai-ml/)** - RAG, fine-tuning, and strategic AI guides\n- **[Architecture](docs/architecture/)** - System design and technical architecture\n- **[Development](docs/development/)** - Development workflows and tools\n- **[Deployment](docs/deployment/)** - Production deployment and operations\n\n### **Key Features:**\n- **Strategic AI** - Multi-tenant organizational intelligence with SWOT/Porter's analysis\n- **Hybrid RAG** - Fine-tuned DNA models + dynamic strategy RAG\n- **GraphQL API** - Modern API with real-time strategic insights (Strawberry)\n- **Containerized Stack** - Docker-based development with hot reload\n- **Web-First Development** - Fast iteration with React/TypeScript\n- **Business Presentations** - Complete pitch deck collection\n\n### **📱 Mobile Development:**\nMobile development has been moved to a separate repository to enable faster web iteration. The mobile app will consume the same REST and GraphQL APIs when ready, ensuring consistency across platforms.\n\n### **🚀 Quick API Access:**\n- **REST API**: \u003chttp://localhost:8000/docs\u003e (Swagger UI)\n- **GraphQL**: \u003chttp://localhost:8000/graphql\u003e (GraphQL Playground)\n- **API Documentation**: [Complete API Guides](docs/api/)\n\n## 1️⃣ Prerequisites\n\n- **Docker + Docker Compose**\n- **Python 3.11+** (3.13 not recommended — pydantic-core build issues)\n- **Node.js 20+** + npm\n- (Optional) **Ollama** for local LLM testing:\n\n  ```bash\n  brew install ollama\n  ollama pull llama3\n  ```\n\n- OpenAI account with API key (if using OpenAI models)\n\n\u003e 📋 **New to the project?** Start with our [**Complete Documentation Index**](DOCUMENTATION.md) for comprehensive guides and [**Getting Started**](docs/getting-started/) for automated installation scripts and containerization strategies for macOS and Linux.\n\n## 2️⃣ One-time setup\n\n```bash\n# Clone repo\ngit clone \u003cyour-repo-url\u003e living_twin_monorepo\ncd living_twin_monorepo\n\n# Quick setup (recommended)\nmake dev-setup\n\n# Or manual setup:\n# Env\ncp .env.example .env\n# Fill in:\n# OPENAI_API_KEY=sk-...\n# Adjust Neo4j creds if needed (dev default: neo4j/password)\n\n# Install all dependencies\nmake install-deps\n\n# Start services and initialize\nmake docker-up\nmake seed-db\n```\n\n## 3️⃣ Verify setup\n\n- **Neo4j** — \u003chttp://localhost:7474\u003e → login `neo4j` / `password`\n\n  ```cypher\n  SHOW INDEXES WHERE name='docEmbeddings';\n  ```\n\n- **Python deps**\n\n  ```bash\n  .venv/bin/python -c \"import fastapi, neo4j, sentence_transformers; print('✅ Python OK')\"\n  ```\n\n- **React admin**\n\n  ```bash\n  make dev-react\n  # Visit http://localhost:5173\n  ```\n\n- **OpenAI key check**\n\n  ```bash\n  make check-billing-py\n  ```\n\n## 4️⃣ Run modes\n\n### Quick Start (Recommended)\n\n```bash\nmake quick-start\n```\n\n- Sets up everything and starts all services\n- Includes sample data and Neo4j initialization\n\n### Development Mode\n\n```bash\nmake docker-up    # Start all services\nmake api-dev      # Run API in development mode\nmake web-dev      # Run admin web interface\nmake mobile-dev   # Run Flutter mobile app\n```\n\n### Local (no OpenAI cost)\n\n```bash\n# Set in .env: LOCAL_EMBEDDINGS=1, RAG_ONLY=1\nmake docker-up\n```\n\n- Local embeddings: `all-MiniLM-L6-v2` (384-dim)\n- Stub LLM: RAG_ONLY=1 (just returns top snippets)\n\n### OpenAI (cheap dev)\n\n```bash\n# Set in .env: LLM_PROVIDER=openai\nmake docker-up\n```\n\n- LLM: `gpt-4o-mini`\n- Embeddings: `text-embedding-3-small` (1536-dim)\n\n### Ollama (local LLM)\n\n```bash\nollama serve \u0026\n# Set in .env: LLM_PROVIDER=ollama\nmake docker-up\n```\n\n## 5️⃣ Demo flow\n\n1. **Quick Start**:\n\n   ```bash\n   make quick-start\n   ```\n\n2. **Access the interfaces**:\n   - **Admin Web**: \u003chttp://localhost:5173\u003e\n   - **API Docs**: \u003chttp://localhost:8000/docs\u003e\n   - **Neo4j Browser**: \u003chttp://localhost:7474\u003e\n\n3. **Test the system**:\n   - **Ingest a snippet**\n     - Paste: \"Fix bug X and raise NPS by 5 points in Q3\"\n     - Title: \"Retention Strategy Q3\"\n     - Click **Ingest**\n   - **Ask a question**\n     - \"How do we improve retention according to the latest plan?\"\n     - Answer should cite `[1] Retention Strategy Q3`\n   - **Debug RAG**\n     - Show retrieved chunks + scores, grouped by source\n\n4. **Test authentication**:\n   - Sign in with `john@acme.com` (auto-binds to Acme Corporation)\n   - Try invitation code: `APRIO-ACME-INV123456789`\n\n## 6️⃣ CLI ingestion/query\n\n```bash\n# Ingest\ncurl -s -X POST http://localhost:8000/ingest/text \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"title\":\"Retention Strategy Q3\",\"text\":\"Fix bug X and raise NPS by 5 points.\",\"tenantId\":\"demo\"}' | jq\n\n# Recent\ncurl -s http://localhost:8000/ingest/recent | jq\n\n# Query\ncurl -s -X POST http://localhost:8000/query \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"question\":\"How do we improve retention?\", \"k\":5, \"tenantId\":\"demo\"}' | jq\n\n# Health check\ncurl -s http://localhost:8000/healthz | jq\n```\n\n## 7️⃣ Common gotchas\n\n| Issue | Fix |\n|-------|-----|\n| **`No such vector schema index: docEmbeddings`** | Run `make neo4j-init` |\n| **Quota exceeded** from OpenAI | Enable Pay-as-you-go in OpenAI billing, or switch to LOCAL_EMBEDDINGS=1 |\n| **pydantic-core build error** | Use Python 3.11 or 3.12 |\n| **Auth error to Neo4j** | Reset volume: `docker compose down -v \u0026\u0026 make neo4j-up \u0026\u0026 make neo4j-init` |\n| **Vectors dim mismatch** | Re-ingest docs after changing embedding model |\n\n## 8️⃣ Environment toggles\n\nIn `.env`:\n\n```bash\nLLM_PROVIDER=openai       # openai | ollama | stub\nLLM_MODEL=gpt-4o-mini\nEMBEDDINGS_MODEL=text-embedding-3-small\nLOCAL_EMBEDDINGS=0        # 1 = use sentence-transformers locally\nLOCAL_EMBEDDINGS_MODEL=sentence-transformers/all-MiniLM-L6-v2\nRAG_ONLY=0                # 1 = skip LLM, just return top snippets\n\n# Ollama settings\nOLLAMA_BASE=http://localhost:11434\nOLLAMA_MODEL=llama3\n```\n\n## 9️⃣ Development Tools\n\n### **Testing**\n\n```bash\nmake test              # Run all tests\nmake test-unit         # Unit tests only\nmake test-integration  # Integration tests only\nmake lint              # Run linters\nmake format            # Format code\n```\n\n### **Database Management**\n\n```bash\nmake seed-db           # Populate with sample data\nmake init-schema       # Initialize Neo4j schema\nmake validate-schema   # Validate Neo4j constraints\n```\n\n### **Monitoring \u0026 Debugging**\n\n```bash\nmake docker-logs       # View container logs\nmake status            # Check service status\nmake logs-api          # API logs (production)\nmake logs-worker       # Worker logs (production)\n```\n\n### **Cost Management**\n\n```bash\nmake check-costs ENV=dev PROJECT=your-project\nmake cost-optimize-dev PROJECT=your-project\nmake scale-down-staging PROJECT=your-project\n```\n\n## 🔟 Testing \u0026 CI/CD\n\n### **Automated Testing**\n\nThe project includes comprehensive test suites:\n\n- **Unit Tests**: `apps/api/tests/test_services.py`, `test_routes.py`\n- **Integration Tests**: `apps/api/tests/test_integration.py`\n- **Load Testing**: `tools/scripts/load-test.js` (k6)\n\n### **GitHub Actions**\n\n- **Continuous Integration**: `.github/workflows/deploy-cloud-run.yml`\n- **Automated Testing**: Runs on every PR and push\n- **Security Scanning**: Trivy vulnerability scanner\n- **Performance Testing**: k6 load tests on staging\n- **Deployment**: Automated deployment to Cloud Run\n\n### **Quality Assurance**\n\n```bash\nmake lint              # Code linting (flake8, mypy)\nmake test              # Full test suite\nmake format            # Code formatting (black, isort)\n```\n\n## 1️⃣1️⃣ Next steps\n\n- Add PDF/DOCX ingestion (`unstructured` lib)\n- Wire API Gateway + Firebase Auth in staging\n- Add multi-tenant plugin marketplace\n- Extend graph schema for goals/teams/projects links\n- Introduce agents with **Ping / Act / Aggregate** modes\n\n## 📚 Documentation\n\nFor detailed documentation on specific topics, see the [`docs/`](docs/) directory:\n\n### Architecture \u0026 Design\n\n- [**Architecture Overview**](docs/ARCHITECTURE.md) - System architecture and design patterns\n- [**Schema Consistency Guide**](docs/SCHEMA_CONSISTENCY_GUIDE.md) - Data models and schema management\n- [**Configuration Sync**](docs/CONFIGURATION_SYNC.md) - Environment and configuration management\n\n### Development \u0026 Deployment\n\n- [**Development Environment Setup**](docs/DEVELOPMENT_ENVIRONMENT_SETUP.md) - External tools, containerization strategies, and automated setup scripts\n- [**Local Development Setup**](docs/README_LOCAL_DEV.md) - Detailed local development guide\n- [**Deployment Setup**](docs/DEPLOYMENT_SETUP.md) - Production deployment instructions\n- [**Deployment Sprint Guide**](docs/DEPLOYMENT_SPRINT_GUIDE.md) - Step-by-step deployment process\n- [**Scaling \u0026 Cost Guide**](docs/SCALING_AND_COST_GUIDE.md) - Performance optimization and cost management\n\n### Features \u0026 Implementation\n\n- [**Conversational Evolution Guide**](docs/CONVERSATIONAL_EVOLUTION_GUIDE.md) - Chat and conversation features\n- [**Conversational Implementation Guide**](docs/CONVERSATIONAL_IMPLEMENTATION_GUIDE.md) - Technical implementation details\n- [**PubSub Event System**](docs/PUBSUB_EVENT_SYSTEM.md) - Event-driven architecture\n- [**PDF/DOCX Ingestion**](docs/pdf-docx-ingestion.md) - Document processing capabilities\n\n### Security \u0026 Operations\n\n- [**Security \u0026 Performance Testing**](docs/SECURITY_AND_PERFORMANCE_TESTING.md) - Testing strategies and security\n- [**Tenant Isolation \u0026 Authorization**](docs/TENANT_ISOLATION_AND_AUTHORIZATION.md) - Multi-tenant security\n\n### Release Notes\n\n- [**README Patch Notes**](docs/README_PATCH.md) - Recent changes and updates\n\n### Development Workflow\n\n- [**Git Setup Guide**](docs/GIT_SETUP_GUIDE.md) - Repository initialization and Git best practices\n- [**GitHub Setup Guide**](docs/GITHUB_SETUP_GUIDE.md) - GitHub integration and CI/CD configuration\n\nEach document provides in-depth coverage of its respective topic with implementation details, best practices, and troubleshooting guides.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkpernyer%2Fliving-twin-monorep","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkpernyer%2Fliving-twin-monorep","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkpernyer%2Fliving-twin-monorep/lists"}