Code Project Documentation

Use Basic Memory to create and maintain comprehensive project documentation alongside your code

Basic Memory excels at creating living documentation that evolves with your project. By co-locating documentation with code and using structured semantic patterns, you can maintain comprehensive project knowledge that stays current and useful.

Getting Started

Setting Up Project Documentation

Create a Basic Memory project within your codebase:

# Create docs folder in your project
mkdir docs

# Initialize Basic Memory project
basic-memory project add my-project ~/code/my-project/docs

# Start working
cd ~/code/my-project

Example Folder Structure

my-project/
├── src/
├── tests/
├── docs/           # Basic Memory knowledge base
│   ├── architecture/
│   │   ├── system-overview.md
│   │   ├── database-design.md
│   │   └── api-design.md
│   ├── decisions/
│   │   ├── adr-001-framework-choice.md
│   │   ├── adr-002-database-selection.md
│   │   └── template.md
│   ├── guides/
│   │   ├── setup.md
│   │   ├── development.md
│   │   └── deployment.md
│   ├── patterns/
│   │   ├── error-handling.md
│   │   ├── validation.md
│   │   └── testing.md
│   └── api/
│       ├── authentication.md
│       ├── endpoints.md
│       └── models.md
└── README.md

Documentation Patterns

System Architecture Documentation

Document your system’s architecture with observations and relations:

---
title: System Architecture Overview
tags: [architecture, system-design]
---

# System Architecture Overview

## Components

### Frontend
- [component] React application with TypeScript #frontend
- [responsibility] User interface and client-side logic #ui
- [technology] Vite for build tooling #build

### Backend API
- [component] FastAPI Python service #backend
- [responsibility] Business logic and data access #api
- [technology] PostgreSQL database with SQLAlchemy #database

### Infrastructure
- [component] Docker containers for deployment #infrastructure
- [responsibility] Service orchestration and scaling #deployment
- [technology] Kubernetes for container management #kubernetes

## Data Flow
- [flow] Client requests → API Gateway → Backend Service #data-flow
- [pattern] Request/Response with JSON payloads #api-pattern
- [security] JWT authentication for protected endpoints #auth

## Relations
- implements [[API Design Principles]]
- uses [[Database Schema]]
- deployed_via [[Kubernetes Configuration]]
- follows [[Security Guidelines]]

API Documentation

Document APIs with practical examples and technical details:

---
title: User Authentication API
tags: [api, authentication, endpoints]
---

# User Authentication API

## POST /auth/login

### Purpose
- [endpoint] User authentication and session creation #auth
- [input] Email and password credentials #credentials
- [output] JWT access token and refresh token #tokens

### Request Format
{
  "email": "user@example.com",
  "password": "securepassword"
}

### Response Format
{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "expires_in": 3600,
  "user": {
    "id": "123",
    "email": "user@example.com",
    "name": "John Doe"
  }
}

## Implementation Details
- [security] Password hashing with bcrypt #security
- [validation] Email format validation required #validation
- [rate-limiting] Maximum 5 attempts per minute per IP #rate-limiting
- [storage] Refresh tokens stored in Redis #storage
- [expiry] Access tokens expire in 1 hour #token-expiry

## Error Responses
- [error] 400 - Invalid request format #validation-error
- [error] 401 - Invalid credentials #auth-error
- [error] 429 - Rate limit exceeded #rate-limit-error

## Relations
- implements [[Authentication Strategy]]
- uses [[User Model]]
- requires [[Rate Limiting Middleware]]
- validates_with [[Input Validation]]

Architecture Decision Records (ADRs)

Use Basic Memory’s semantic format for structured decision documentation:

---
title: "ADR-001: Database Technology Selection"
tags: [adr, database, decisions, postgresql]
---

# ADR-001: Database Technology Selection

## Status
- [status] Accepted #decision-status
- [date] 2024-01-15 #decision-date
- [impact] High - affects entire data layer #impact

## Context
We need to select a database technology for our financial application that handles user transactions, account balances, and reporting data.

## Decision
Selected PostgreSQL over MongoDB and MySQL.

## Rationale

### Requirements Analysis
- [requirement] ACID compliance for financial transactions #acid
- [requirement] Complex analytical queries for reporting #analytics
- [requirement] Strong consistency guarantees #consistency
- [requirement] Mature ecosystem and tooling #ecosystem

### Technology Evaluation

#### PostgreSQL (Selected)
- [advantage] Full ACID compliance #acid
- [advantage] Advanced SQL features (CTEs, window functions) #sql-features
- [advantage] JSON support for flexible schemas #json
- [advantage] Excellent Python/SQLAlchemy integration #python
- [advantage] Strong performance for analytical queries #performance
- [consideration] Requires SQL expertise in team #team-skills

#### MongoDB
- [disadvantage] Limited ACID guarantees across collections #acid-limitation
- [advantage] Flexible schema design #schema-flexibility
- [disadvantage] Complex analytical queries #query-complexity
- [consideration] NoSQL learning curve for team #learning-curve

#### MySQL
- [advantage] ACID compliance #acid
- [disadvantage] Limited analytical query features #analytics-limitation
- [advantage] Wide ecosystem support #ecosystem
- [consideration] Less advanced features than PostgreSQL #feature-gap

## Consequences

### Positive
- [benefit] Strong data consistency for financial operations #consistency
- [benefit] Powerful querying capabilities for reports #reporting
- [benefit] Mature tooling and monitoring #tooling
- [benefit] Team already has SQL expertise #team-alignment

### Negative
- [cost] More complex setup than document databases #complexity
- [cost] Requires careful schema design #schema-planning
- [mitigation] Using Alembic for migration management #migration-strategy

### Neutral
- [impact] Standard SQL patterns familiar to team #familiarity
- [impact] Good performance characteristics for our scale #performance

## Implementation Notes
- [tool] Using SQLAlchemy 2.0 for ORM #orm
- [tool] Alembic for database migrations #migrations
- [tool] asyncpg for async database connections #async
- [monitoring] PostgreSQL-specific monitoring setup #monitoring

## Relations
- affects [[Database Schema Design]]
- requires [[Migration Strategy]]
- implements [[Data Architecture]]
- influences [[Performance Monitoring]]
- supports [[Financial Transaction Processing]]

Development Workflows

Daily Documentation Practice

Morning startup:

You (to AI): "What documentation updates are needed based on recent commits?"
AI: [Reviews git log and suggests documentation updates]

During development:

You: "Document the new user preference system we just implemented"
AI: [Creates comprehensive documentation with code examples and relations]

End of sprint:

You: "Update our architecture overview with the changes from this sprint"
AI: [Reviews changes and updates architectural documentation]

Code Review Integration

Before creating PR:

# Check if documentation is current
basic-memory tools search-notes --query "authentication system"

# Update documentation
echo "Updated authentication to support OAuth2 flows" | \
basic-memory tools write-note --title "Sprint 12 - Auth Updates" --folder "updates"

During code review:

Reference specific architecture decisions: memory://decisions/database-choice
Link to relevant patterns: memory://patterns/error-handling
Check if new patterns need documentation

Onboarding new developers:

---
title: Developer Onboarding Guide
tags: [onboarding, team, setup]
---

# Developer Onboarding Guide

## Essential Reading
- [architecture] Start with [[System Architecture Overview]] #overview
- [decisions] Review all [[ADR]] documents #decisions
- [patterns] Study [[Coding Patterns]] we follow #patterns
- [api] Understand [[API Design Principles]] #api

## Setup Checklist
- [ ] Clone repository and run setup script
- [ ] Install Basic Memory: `uv tool install basic-memory`
- [ ] Review architecture documents
- [ ] Complete coding exercise
- [ ] Pair with senior developer for first feature

## Key Concepts
- [pattern] We use semantic documentation with observations #documentation
- [practice] All architectural decisions are documented as ADRs #adr
- [practice] API changes require documentation updates #api-docs
- [practice] Complex business logic gets decision documentation #business-logic

## Relations
- references [[System Architecture Overview]]
- includes [[Development Setup Guide]]
- requires [[Coding Standards]]

Advanced Patterns

Living Documentation

Keep documentation synchronized with code changes:

## Database Schema Evolution

### Version 1.2 (Current)
- [change] Added user_preferences table #schema-change
- [migration] Migration 2024-01-15-add-preferences.sql #migration
- [breaking] Removed deprecated profile_data column #breaking-change

### Version 1.1
- [change] Added indexes for performance #performance
- [migration] Migration 2024-01-01-add-indexes.sql #migration

## Relations
- documented_in [[Migration Guide]]
- affects [[User Model]]
- requires [[Database Migration Strategy]]

Cross-Project Documentation

Link related concepts across projects:

## Shared Components

### Authentication Library
- [component] Shared across all microservices #shared-component
- [repository] `basic-auth-lib` repository #repository
- [documentation] See memory://shared/auth-library #cross-reference

### API Gateway Configuration
- [component] Central routing and rate limiting #gateway
- [repository] `api-gateway` repository #repository
- [documentation] See memory://infrastructure/api-gateway #cross-reference

## Relations
- uses [[Shared Authentication Library]]
- configured_in [[API Gateway Project]]

Integration with Git

Use git hooks to maintain documentation:

# Pre-commit hook to check documentation currency
#!/bin/bash
# Check if any API files changed without corresponding docs update
if git diff --cached --name-only | grep -q "^src/api/"; then
    if ! git diff --cached --name-only | grep -q "^docs/api/"; then
        echo "API changes detected. Please update API documentation."
        exit 1
    fi
fi

Best Practices

Documentation Standards

Use semantic patterns - Employ observations with categories and tags
Create rich relations - Link related concepts extensively
Include code examples - Show practical implementations
Document decisions - Capture the “why” not just the “what”
Keep it current - Update docs with code changes

Organization Tips

Consistent naming - Use kebab-case for file names
Clear hierarchy - Organize by functional areas
Template usage - Create templates for common document types
Regular reviews - Schedule documentation review sessions
Git integration - Version control documentation with code

Team Collaboration

Shared vocabulary - Use consistent terminology across docs
Review process - Include documentation in code reviews
Onboarding guides - Create clear paths for new team members
Knowledge sharing - Regular documentation sessions
Tool training - Ensure team knows Basic Memory patterns

Common Document Types

Templates

API Endpoint Template:

---
title: [Endpoint Name]
tags: [api, endpoint-category]
---

# [Endpoint Name]

## Purpose
- [endpoint] Brief description #category
- [input] Input parameters #input
- [output] Response format #output

## Implementation
- [method] HTTP method and path #http
- [validation] Input validation rules #validation
- [authorization] Authentication requirements #auth

## Relations
- implements [[API Design Pattern]]
- uses [[Model Name]]

Architecture Decision Template:

---
title: ADR-XXX: [Decision Title]
tags: [adr, category]
---

# ADR-XXX: [Decision Title]

## Status
- [status] Proposed/Accepted/Deprecated #status

## Context
[Background and problem statement]

## Decision
[What was decided]

## Consequences
- [benefit] Positive outcomes #benefit
- [cost] Negative impacts #cost
- [mitigation] How costs are addressed #mitigation

## Relations
- affects [[Related Component]]
- supersedes [[Previous ADR]]

Code Project Documentation

Getting Started

Setting Up Project Documentation

Example Folder Structure

Documentation Patterns

System Architecture Documentation

API Documentation

Architecture Decision Records (ADRs)

Development Workflows

Daily Documentation Practice

Code Review Integration

Advanced Patterns

Living Documentation

Cross-Project Documentation

Integration with Git

Best Practices

Documentation Standards

Organization Tips

Team Collaboration

Common Document Types

Templates

Troubleshooting

Common Issues

Next Steps

Architecture Decisions

Note Taking

Knowledge Format

CLI Reference

Code Project Documentation

Getting Started

Setting Up Project Documentation

Example Folder Structure

Documentation Patterns

System Architecture Documentation

API Documentation

Architecture Decision Records (ADRs)

Development Workflows

Daily Documentation Practice

Code Review Integration

Team Knowledge Sharing

Advanced Patterns

Living Documentation

Cross-Project Documentation

Integration with Git

Best Practices

Documentation Standards

Organization Tips

Team Collaboration

Common Document Types

Templates

Troubleshooting

Common Issues

Next Steps

Architecture Decisions

Note Taking

Knowledge Format

CLI Reference