Skip to content

README.md

Latest commit

 

History

History
280 lines (201 loc) · 12.5 KB

README.md

File metadata and controls

280 lines (201 loc) · 12.5 KB

📚 Discogsography Documentation

Comprehensive guides and documentation for the Discogsography platform

🏠 Back to Main | 🤖 Claude Guide | 📋 Emoji Guide

📖 Documentation Index

🚀 Getting Started

Document Description
Quick Start Guide ⚡ Get Discogsography running in minutes
Configuration Guide ⚙️ Complete environment variable and settings reference
Architecture Overview 🏛️ System architecture, components, and data flow

📊 Core Guides

Document Description
Database Schema 🗄️ Complete Neo4j and PostgreSQL schema documentation
Usage Examples 💡 Query examples for Neo4j and PostgreSQL
Monitoring Guide 📊 Real-time monitoring, debugging, and operations
Admin Guide 🔐 Admin account setup, extraction triggers, DLQ ops
Troubleshooting Guide 🔧 Common issues and solutions

👨‍💻 Development

Document Description
Development Guide 💻 Complete developer setup and workflow guide
Contributing Guide 🤝 How to contribute to the project
Testing Guide 🧪 Comprehensive testing strategies and patterns
Logging Guide 📊 Complete logging configuration and best practices
Python Version Management 🐍 Managing Python 3.13+ across the project

🚀 Operations & Infrastructure

Document Description
Docker Security 🔒 Container hardening & security practices
Dockerfile Standards 🐋 Best practices for writing Dockerfiles
Database Resilience 💾 Database connection patterns & error handling
Performance Guide ⚡ Performance optimization strategies
Maintenance Guide 🔧 Keeping the system up-to-date and healthy

⚙️ Workflow & Automation

Document Description
GitHub Actions Guide 🔄 CI/CD workflows, automation & best practices
Task Automation ⚡ Complete just and uv command reference
Monorepo Guide 📦 Managing Python monorepo with shared dependencies

📋 Reference Guides

Document Description
State Marker System 📋 Extraction progress tracking and recovery system
State Marker Periodic Updates 💾 Periodic state saves implementation and crash recovery
Emoji Guide 📋 Standardized emoji usage across the project
Consumer Cancellation 🔄 File completion and consumer lifecycle management
File Completion Tracking 📊 Intelligent completion tracking and stalled detection
Platform Targeting 🎯 Cross-platform compatibility guidelines
Neo4j Indexing 🔗 Advanced Neo4j indexing strategies
Query Performance Optimizations ⚡ Comprehensive query optimization report (249x overall improvement)
MusicBrainz Sync Guide 🎵 MusicBrainz data import, enrichment, and pipeline operations
Recent Improvements 🚀 Latest platform enhancements and changelog

🎯 Documentation by Role

For New Users

Start here to get up and running quickly:

  1. Quick Start Guide - Get Discogsography running
  2. Architecture Overview - Understand the system
  3. Usage Examples - Try some queries
  4. Configuration Guide - Customize settings

For Developers

Get set up for development and understand our workflows:

  1. Development Guide - Set up your dev environment
  2. Contributing Guide - Learn how to contribute
  3. Testing Guide - Write and run tests
  4. Logging Guide - Follow logging standards
  5. GitHub Actions Guide - Understand CI/CD

For DevOps Engineers

Deploy and maintain Discogsography in production:

  1. Docker Security - Secure container practices
  2. Dockerfile Standards - Build optimization
  3. Configuration Guide - Production settings
  4. Monitoring Guide - Observe and debug
  5. Admin Guide - Admin accounts and extraction management
  6. Performance Guide - Optimize performance
  7. Maintenance Guide - Keep systems healthy

For Data Engineers

Work with the music data and databases:

  1. Database Schema - Understand data structures
  2. Usage Examples - Query the databases
  3. Performance Guide - Optimize queries
  4. Database Resilience - Connection patterns

For Troubleshooting

When things go wrong:

  1. Troubleshooting Guide - Common issues and fixes
  2. Monitoring Guide - Debug and diagnose
  3. Logging Guide - Configure logging and debug
  4. Performance Guide - Performance issues

📝 Documentation Standards

When creating or updating documentation:

File Naming

  • Use lowercase with hyphens: new-feature-guide.md
  • Be descriptive: database-backup-procedures.md not db-backup.md
  • Avoid abbreviations unless widely known (e.g., api, sql)

Structure

  • Header: Title, description, and navigation links
  • Overview: Brief introduction to the topic
  • Sections: Organized with clear headings
  • Examples: Practical code examples where applicable
  • Related Docs: Links to related documentation
  • Last Updated: Date at the bottom

Content Guidelines

  • Clear and concise: Get to the point quickly
  • Code examples: Include working code snippets
  • Commands: Show exact commands to run
  • Screenshots: Use where helpful (but don't overdo it)
  • Emojis: Follow the Emoji Guide
  • Diagrams: Use Mermaid for architecture and flow diagrams

Mermaid Diagrams

  • Use consistent styling across diagrams
  • Include meaningful colors (see existing docs for palette)
  • Keep diagrams simple and focused
  • Add alt text for accessibility

Example Header Format

# 🔧 Document Title

<div align="center">

**Brief description of what this document covers**

[🏠 Back to Main](../README.md) | [📚 Documentation Index](README.md) | [Related Doc](related-doc.md)

</div>

## Overview

Brief introduction to the topic...

🤝 Contributing to Documentation

To add or improve documentation:

  1. Create or edit a .md file in this directory
  2. Follow naming convention: lowercase-with-hyphens.md
  3. Use the standard header format shown above
  4. Add to this README in the appropriate section
  5. Update main README.md if it's a major guide
  6. Test all code examples to ensure they work
  7. Check all links are valid and point to the right place
  8. Run spell check before committing

Documentation Checklist

Before submitting documentation changes:

  • File name follows convention (lowercase-with-hyphens)
  • Header includes title, description, and navigation
  • Overview section explains the purpose
  • Code examples are tested and work
  • All links are valid
  • Emojis follow the emoji guide
  • Mermaid diagrams render correctly
  • "Last Updated" date is current
  • Added to docs/README.md index
  • Updated main README.md if needed
  • Spell-checked and proofread

📊 Documentation Coverage

Current documentation covers:

  • ✅ Getting started and quick setup
  • ✅ Complete architecture documentation
  • ✅ Configuration and environment variables
  • ✅ Database schemas and usage examples
  • ✅ Development environment setup
  • ✅ Testing strategies and patterns
  • ✅ CI/CD workflows and automation
  • ✅ Docker and containerization
  • ✅ Security best practices
  • ✅ Performance optimization
  • ✅ Monitoring and debugging
  • ✅ Troubleshooting common issues
  • ✅ Maintenance and operations
  • ✅ Contributing guidelines

🔍 Finding Documentation

Search Tips

By Topic:

By Service:

  • Each service has its own README in the service directory
  • See architecture docs for service interaction diagrams
  • Check monitoring docs for service-specific debugging

By Use Case:

  • Setting up for the first time → Quick Start
  • Adding a feature → Development & Contributing
  • Debugging an issue → Troubleshooting & Monitoring
  • Deploying to production → Configuration & Security
  • Optimizing performance → Performance & Database guides

💬 Getting Help

If you can't find what you're looking for:

  1. Search this index - Use Cmd+F/Ctrl+F to search this page
  2. Check CLAUDE.md - AI development guidance
  3. Read service READMEs - Service-specific docs in each directory
  4. Browse GitHub Discussions - Q&A and community help
  5. Create an issue - Report documentation gaps

📈 Documentation Metrics

Help us improve documentation:

Last Updated: 2026-04-03

Made with ❤️ by the Discogsography community