Listopia Documentation Map

April 29, 2026 · View on GitHub

Quick reference for finding the right documentation for your task.

🚀 Quick Start by Task

I want to understand the project architecture

→ Start with CLAUDE.md

  • Stack overview
  • Architecture patterns
  • Key models and conventions
  • Frontend approach
  • Chat System Architecture section (350+ lines)

I'm implementing intelligent list creation

→ Read CHAT_CONTEXT.md

  • System overview and architecture
  • Service pipeline (detection, analysis, generation)
  • State machine and flows
  • UI components and real-time feedback
  • Testing and data migration

I'm implementing a chat feature

→ Read CHAT_FEATURES.md

  • Quick start examples
  • How to add commands
  • How to add LLM tools
  • How to create message templates
  • Authorization patterns
  • Testing scenarios
  • Troubleshooting guide

I'm working with search or RAG

→ Read RAG_SEMANTIC_SEARCH.md

  • How embeddings work
  • Hybrid search (vector + keyword)
  • RAG context building
  • Database setup with pgvector
  • Performance optimization
  • Integration with chat

I'm debugging a problem

→ Use CHAT_FEATURES.md - Debugging & Troubleshooting → Or RAG_SEMANTIC_SEARCH.md - Troubleshooting

I'm writing tests

→ See CHAT_FEATURES.md - Testing Scenarios

I need API endpoint documentation

→ See RAG_SEMANTIC_SEARCH.md - API Endpoints

I'm building or configuring AI Agents

→ Read AGENTS.md

  • Agent scopes and access control (system, org, team, user)
  • Resources and tool management
  • Execution flow and orchestration
  • Authorization rules
  • Data models and controllers

I'm integrating third-party services

→ Read CONNECTORS_ARCHITECTURE.md

  • Complete connector overview
  • Implementation status (6 phases complete)
  • Security model and encryption
  • OAuth implementations (Google, Microsoft, Slack)

→ Then CONNECTORS_SECURITY_CHECKLIST.md

  • Pre-testing security verification
  • Token encryption validation
  • Multi-layer authorization testing
  • CSRF protection verification

I want historical context

→ See archived/README.md

  • Why decisions were made
  • Original architectural proposals
  • Implementation history

📚 Complete Documentation Structure

CLAUDE.md (Master Reference)
├── Stack Overview
├── Architecture Patterns
├── Key Models
├── Organizations & Teams Architecture ✅
├── Chat System Architecture ✅ (NEW - 350+ lines)
│   ├── Overview
│   ├── Command System
│   ├── Intent Detection
│   ├── Resource Creation Flow
│   ├── Message Types & Templates
│   ├── Authorization & Data Boundaries
│   ├── Services & Components
│   ├── UI/UX Patterns
│   └── Example Flows
├── Frontend Approach
│   └── Chat UI Patterns ✅ (NEW)
├── Common Tasks
└── Development Standards

AGENTS.md (AI Agents System) ✅ NEW
├── Overview & Architecture
├── Agent Scopes & Access Control
├── Agent Configuration
├── Resources & Tools
├── Execution Flow & Lifecycle
├── Orchestration (Agent → Agent)
├── Data Models
├── Routes & Controllers
├── Security & Authorization
├── Performance Considerations
├── Troubleshooting
└── Future Enhancements

CHAT_CONTEXT.md (Chat Context Management) ✅ NEW
├── Understanding Chat Context
├── Implementation Details
│   ├── Phase 1: Models & Database
│   ├── Phase 2: Core Services
│   ├── Phase 3: ChatCompletionService Integration
│   ├── Phase 4: List Creation
│   ├── Phase 5: User Interface
│   └── Phase 6: Testing & Migration
├── Flows (Simple & Complex)
├── Common Patterns
└── Testing & Deployment

CHAT_FEATURES.md (Implementation Guide)
├── Quick Start
├── Architecture Overview
├── How to Add Features
│   ├── Add a Command
│   ├── Add an LLM Tool
│   ├── Add a Message Template
│   └── Add a Navigation Route
├── Available Tools Reference
├── Message Templates
├── Authorization & Security
├── Testing Scenarios
├── Debugging & Troubleshooting
├── Common Issues & Solutions
├── File Locations
└── Performance Optimization

RAG_SEMANTIC_SEARCH.md (Search & RAG Guide)
├── Overview
├── Core Concepts
│   ├── Embeddings
│   ├── Vector Similarity Search
│   ├── Full-Text Search
│   └── Relevance Scoring
├── Architecture
├── Database Setup
├── Embedding Generation
├── Hybrid Search
├── RAG Integration
├── Search vs. Navigation Decision Tree
├── API Endpoints
├── Internal Services
├── Integration with Chat
├── Performance & Optimization
├── Troubleshooting
└── Future Enhancements

CONNECTORS_ARCHITECTURE.md (Third-Party Integrations) ✅ NEW
├── Overview & Implementation Status
├── Architecture Overview (6 phases complete)
├── Directory Structure
├── Database Schema
├── Key Architectural Patterns
├── Security Implementation
├── OAuth Implementations
├── Connector Features
├── API Operations
├── Testing
├── Routes
├── Future Enhancements
├── Deployment
└── Monitoring

CONNECTORS_SECURITY_CHECKLIST.md (Pre-Testing Verification) ✅ NEW
├── Pre-Testing Security Verification
├── Token Encryption & Storage
├── Multi-Layer Authorization
├── OAuth Security
├── Data Isolation & Multi-Tenancy
├── Error Handling & Incident Response
├── Logging & Audit Trail
├── Deployment Security
├── Rate Limiting & Abuse Prevention
├── Secrets Rotation
├── Testing Checklist
├── Production Checklist
└── Incident Response Procedures

CONNECTORS_GOOGLE_CALENDAR.md (Google Calendar Details)
├── Architecture
├── OAuth Flow
├── Event Sync
├── Error Handling
└── Future Enhancements

CONNECTORS_MICROSOFT_OUTLOOK.md (Microsoft Outlook Details)
├── Architecture
├── PKCE Implementation
├── Event Sync
├── Differences from Google
└── Error Handling

CONNECTORS_SLACK.md (Slack Details)
├── Architecture
├── OAuth Flow
├── Message Posting
├── Webhook Handling
└── Error Handling

CONNECTORS_GOOGLE_DRIVE.md (Google Drive Details)
├── Architecture
├── File Browsing
├── API Operations
├── Future Enhancements
└── Error Handling

CONNECTORS_OAUTH.md (OAuth Implementation)
├── OAuth 2.0 Patterns
├── State Parameter Validation
├── Token Lifecycle
└── Error Handling

CONNECTORS_SECURITY.md (Security Model)
├── Authentication & Authorization
├── OAuth Security
├── User Isolation
├── Incident Handling
├── Deployment Requirements
└── Future Enhancements

docs/archived/README.md (Historical Reference)
├── CHAT_ARCHITECTURE_PROPOSAL.md
├── CHAT_IMPLEMENTATION_SUMMARY.md
├── UNIFIED_CHAT_IMPLEMENTATION.md
├── CHAT_INTEGRATION_COMPLETE.md
├── RAG_SEARCH_IMPLEMENTATION_STATUS.md
└── API_ENDPOINTS_RAG_SEARCH.md

🎯 By Developer Role

Backend Developer (Ruby/Rails)

Essential Reading:

  1. CLAUDE.md - Project overview
  2. CHAT_FEATURES.md - How to add features
  3. RAG_SEMANTIC_SEARCH.md - Search implementation

Key Sections:

  • Architecture patterns (models, services)
  • Authorization & security
  • Testing scenarios
  • File locations

Frontend Developer (JavaScript/Stimulus)

Essential Reading:

  1. CLAUDE.md - Chat UI Patterns
  2. CHAT_FEATURES.md - Message Templates
  3. RAG_SEMANTIC_SEARCH.md - API Endpoints

Key Sections:

  • Form handling and input clearing
  • Message rendering
  • Turbo Stream integration
  • Stimulus controllers

AI Agent (Claude Code)

Recommended Starting Point:

  1. CLAUDE.md - Comprehensive reference
  2. CHAT_FEATURES.md - Implementation patterns
  3. RAG_SEMANTIC_SEARCH.md - Search details

Key Sections:

  • Development standards
  • Authorization patterns
  • File locations
  • Testing checklist

🔍 By Topic

AI Agents

Chat System

Chat Context & List Planning

Search & RAG

Authentication & Authorization

Models & Database

Frontend & UI

Testing

Third-Party Integrations (Connectors)

📋 File Organization

In Project Root (Active)

FilePurposeLinesWhen to Use
CLAUDE.mdMaster development reference750+First resource for any question
CHAT_FEATURES.mdChat implementation guide850+Building chat features
RAG_SEMANTIC_SEARCH.mdSearch & RAG guide800+Working with search/embeddings
CONNECTORS_ARCHITECTURE.mdThird-party integrations500+Working with connectors (OAuth, sync, webhooks)
CONNECTORS_SECURITY_CHECKLIST.mdPre-testing security verification400+Before testing connector functionality
README.mdThis file-Finding the right doc

In docs/ (AI Agents - Active)

FilePurposeLinesWhen to Use
AGENTS.mdAI Agents system architecture400+Building or configuring agents, managing resources/tools

In docs/ (Chat Context - Active)

FilePurposeLinesWhen to Use
CHAT_CONTEXT.mdChat context & list planning system350+Implementing intelligent list creation

In docs/ (Connectors - Active)

FilePurposeWhen to Use
CONNECTORS_OAUTH.mdOAuth 2.0 implementationUnderstanding OAuth patterns across all connectors
CONNECTORS_SECURITY.mdDetailed security modelDeep dive on authorization, encryption, error handling
CONNECTORS_GOOGLE_CALENDAR.mdGoogle Calendar specificsWorking with calendar sync and events
CONNECTORS_MICROSOFT_OUTLOOK.mdMicrosoft Outlook specificsWorking with Outlook calendars (PKCE flow)
CONNECTORS_SLACK.mdSlack specificsWorking with messaging, webhooks, notifications
CONNECTORS_GOOGLE_DRIVE.mdGoogle Drive specificsWorking with file browsing and metadata

In docs/archived/ (Reference Only)

FileHistorical ContentWhy Archived
CHAT_ARCHITECTURE_PROPOSAL.mdOriginal 18-part proposalSuperseded by CLAUDE.md + CHAT_FEATURES.md
CHAT_IMPLEMENTATION_SUMMARY.mdImplementation snapshotStatus report from implementation phase
UNIFIED_CHAT_IMPLEMENTATION.mdPhase 1 completionStatus report (features now in CHAT_FEATURES.md)
CHAT_INTEGRATION_COMPLETE.mdIntegration detailsDetails now in CLAUDE.md Chat section
RAG_SEARCH_IMPLEMENTATION_STATUS.mdRAG phase statusConsolidated into RAG_SEMANTIC_SEARCH.md
API_ENDPOINTS_RAG_SEARCH.mdSearch API docsContent moved to RAG_SEMANTIC_SEARCH.md

Deleted (Content Consolidated):

  • CHAT_QUICK_START.md → CHAT_FEATURES.md
  • CHAT_SYSTEM.md → CHAT_FEATURES.md
  • QUICK_START_RAG_SEARCH.md → RAG_SEMANTIC_SEARCH.md
  • RAG_SEARCH_INDEX.md → RAG_SEMANTIC_SEARCH.md

🚦 Documentation Quality Standards

All active documentation follows these standards:

✅ Current - Updated with latest implementation details ✅ Accurate - Reflects actual code in repository ✅ Complete - Covers all essential information ✅ Clear - Written for developers and AI agents ✅ Actionable - Includes examples and code samples ✅ Organized - Clear structure with table of contents ✅ Cross-Referenced - Links to related documents ✅ Non-Duplicated - No significant content overlap

📞 Finding Help

Need architecture overview? → CLAUDE.md

Can't find what you're looking for? → Check the table of contents in each doc → Use Ctrl+F to search

Implementing a new feature? → CHAT_FEATURES.md - How to Add Features

Debugging something? → Check "Troubleshooting" section in relevant doc

Want historical context? → docs/archived/README.md

🎓 Learning Path

New to Listopia?

  1. Read CLAUDE.md overview sections
  2. Read CLAUDE.md - Stack Overview
  3. Read CLAUDE.md - Architecture Patterns
  4. Read relevant feature docs (CHAT_FEATURES.md or RAG_SEMANTIC_SEARCH.md)

New to Chat Context & List Planning?

  1. CHAT_CONTEXT.md - Understanding Chat Context
  2. CHAT_CONTEXT.md - Implementation Details
  3. CHAT_CONTEXT.md - Flows
  4. Review the test files to understand usage

New to Chat Features?

  1. CHAT_FEATURES.md - Quick Start
  2. CHAT_FEATURES.md - Architecture Overview
  3. CHAT_FEATURES.md - How to Add Features
  4. Practice: Add a simple command

New to Search/RAG?

  1. RAG_SEMANTIC_SEARCH.md - Overview
  2. RAG_SEMANTIC_SEARCH.md - Core Concepts
  3. RAG_SEMANTIC_SEARCH.md - Architecture
  4. Practice: Test SearchService with real data

Last Updated: 2025-12-10 Documentation Version: 3.0 (Consolidated & Reorganized)