Quickli Documentation
Welcome to the Quickli technical documentation hub. This directory contains architectural decisions, best practices, guides, and operational knowledge for the Quickli platform.
📚 Documentation Structure
Section titled “📚 Documentation Structure”Immutable records of significant technical decisions made by the team. Each ADR captures the context, decision, and consequences of important architectural choices.
When to create an ADR: Major technical decisions, library selections, architectural patterns, significant refactors.
Proven patterns and recommended approaches for common development tasks. Reference these during implementation and code review.
Topics include: Analytics, state management, styling, testing, error handling, API design, code review.
Common mistakes, deprecated approaches, and patterns to avoid. Learn from past mistakes to prevent them in the future.
Topics include: Common mistakes, deprecated approaches, performance pitfalls.
Step-by-step how-to guides and tutorials for common workflows and tasks.
Topics include: Onboarding, adding packages, monorepo workflows, database migrations, deployment.
High-level system design documentation, data flows, and integration points.
Topics include: System overview, data flow, package dependencies, integration points.
Team standards, style guides, and coding conventions. The “house style” for the Quickli codebase.
Topics include: Code style, naming conventions, commit messages, git workflow, file organization.
Operational procedures for debugging, incident response, and common production issues.
Topics include: Incident response, debugging production, common issues.
🤝 Contributing to Documentation
Section titled “🤝 Contributing to Documentation”General Guidelines
Section titled “General Guidelines”- Keep it current: Update docs when you change patterns or make decisions
- Be specific: Include code examples and real scenarios from our codebase
- Link freely: Cross-reference related documentation
- Use markdown: Keep formatting consistent and readable
- No stale content: Remove or update outdated information
Creating an ADR
Section titled “Creating an ADR”ADRs follow a specific format (see adr):
- Copy the ADR template
- Use sequential numbering (e.g.,
0001-your-decision.md) - Fill in context, decision, status, and consequences
- ADRs are immutable once accepted - supersede with new ADRs if needed
Adding Best Practices
Section titled “Adding Best Practices”- Verify the pattern is actually used in the codebase
- Include code examples from real Quickli code
- Explain the “why” not just the “what”
- Link to related ADRs or other documentation
Documenting Anti-Patterns
Section titled “Documenting Anti-Patterns”- Show the problematic pattern
- Explain why it’s problematic
- Provide the preferred alternative
- Link to best practices or ADRs
🔍 Finding Information
Section titled “🔍 Finding Information”Looking for setup instructions? See the main README and Onboarding
Need to understand a decision? Check ADRs
Want to know the right way to do something? See best-practices
Production issue? Start with runbooks
Joining the team? Read guides/onboarding.md and architecture/overview.md
📝 Documentation Philosophy
Section titled “📝 Documentation Philosophy”Good documentation is:
- Discoverable: Easy to find when you need it
- Actionable: Practical guidance, not just theory
- Current: Reflects the actual state of the codebase
- Honest: Documents failures and learnings, not just successes
- Living: Updated as the codebase evolves
Last updated: October 2025