Project Knowledge Base

A reusable, framework-agnostic knowledge base for any software project.

---

🎯 What Is This?

This is a centralized knowledge repository for your project. It gets symlinked into every service, microservice, and app repo so that all code repos share a single source of truth for project context, decisions, patterns, and documentation.

Each service repo structure:

my-service/
├── src/
├── tests/
├── knowledge → ../project-knowledge   ← Symlink to this repo
└── README.md

---

📁 What's Inside

Folder	Purpose
.ai/	AI Memory — context, decisions, patterns, lessons, tasks for AI assistants
docs/	Documentation as Code — 10 numbered folders for organized project docs
scripts/	Setup scripts — initialize knowledge base, create symlinks
templates/	Reusable templates — ADR, PR, service README

AI Memory (.ai/)

File	Purpose
CONTEXT.md	Project overview, architecture, tech stack
DECISIONS.md	Architecture Decision Records (ADRs)
PATTERNS.md	Implementation patterns and conventions
LESSONS.md	Learnings, risks, mitigations
TASKS.md	Task tracking with priorities

Documentation (docs/)

Folder	Purpose
00-source-docs/	Original .docx, .xlsx, .png files (preserved as-is)
01-architecture/	System design, data flow, deployment
02-requirements/	SRS & TRD summaries
03-business-rules/	Policies, user types, pricing
04-guides/	How-to guides
05-standards/	Coding standards, git workflow, testing
06-api-contracts/	API specifications
07-compliance/	Regulatory compliance
08-third-party/	External services
09-onboarding/	New developer guides

---

🚀 Quick Start

1. Clone This Repository

git clone <repo-url> my-project-knowledge
cd my-project-knowledge

2. Run the Init Script

# Mac/Linux/Git Bash
bash scripts/init-project.sh

# Windows PowerShell
.\scripts\init-project.ps1

The script prompts for your project details and fills in all placeholders.

3. Review and Customize

• Edit .ai/CONTEXT.md — fill in remaining details
• Edit .ai/DECISIONS.md — document architecture decisions
• Add source documents to docs/00-source-docs/
• Create markdown summaries in docs/01- through docs/09-

4. Push to Your Organization

git remote set-url origin git@github.com:[org-name]/[project-name]-knowledge.git
git push -u origin main

5. Link Into Service Repos

In each service/app repo, create a symlink:

cd my-service/

# Windows (PowerShell as Admin)
New-Item -ItemType Junction -Path "knowledge" -Target "..\my-project-knowledge"

# Mac/Linux
ln -s ../my-project-knowledge knowledge

See KNOWLEDGE_SETUP.md for detailed setup instructions.

---

🔄 How It Works

Single Source of Truth

project-knowledge/          ← This repo (single source of truth)
├── .ai/CONTEXT.md          ← Project context
├── .ai/DECISIONS.md        ← Architecture decisions
├── docs/01-architecture/   ← Architecture docs
└── ...

service-a/knowledge/  →  symlink to project-knowledge  (instantly up to date)
service-b/knowledge/  →  symlink to project-knowledge  (instantly up to date)
app-web/knowledge/    →  symlink to project-knowledge  (instantly up to date)

When you update the knowledge base, all service repos see the change immediately — no copying, no syncing, no drift.

AI Assistants

When an AI works on any service repo, it reads the symlinked knowledge:

1. .ai/CONTEXT.md — understand the project
2. .ai/DECISIONS.md — respect past decisions
3. .ai/PATTERNS.md — follow established patterns
4. .ai/LESSONS.md — avoid known pitfalls
5. .ai/TASKS.md — track progress

---

📖 Documentation

Document	Description
KNOWLEDGE_SETUP.md	How to set up knowledge symlinks in service repos
.ai/README.md	How the AI memory system works
docs/README.md	How the documentation structure works

---

🤝 Contributing

This knowledge base is:

1. Framework-agnostic — works with any tech stack
2. Cloud-agnostic — works with AWS, GCP, Azure, or self-hosted
3. Team-size-agnostic — works for solo devs to 50-person teams
4. Project-type-agnostic — works for web apps, mobile apps, APIs, microservices

---

Version: 1.0