# Drydown Documentation

**Status**: [See status.md](./status.md) for current implementation progress

## Quick Navigation

### For Feature Development
- [Product Features](./product/features.md) - What we're building (F1-F8)
- [User Flows](./product/user-flows.md) - How users interact with the app
- [Requirements](./product/requirements.md) - Detailed specifications
- [Implementation Roadmap](./implementation/overview.md) - Development phases

### For Technical Implementation
- [Architecture Overview](./architecture/overview.md) - System design
- [Component Structure](./architecture/component-structure.md) - UI organization
- [State Management](./architecture/state-management.md) - State strategy
- [Data Models](./data/data-models.md) - TypeScript types
- [Lexicon Schemas](./data/lexicon-schemas.md) - AT Protocol records
- [Storage Strategy](./data/storage-strategy.md) - Data persistence

### For API Integration
- [AT Protocol Auth](./reference/existing-code.md#authentication) - OAuth flow (already implemented)
- [AT Protocol Repo](./api/atproto-repo.md) - Repository operations
- [Bluesky Posting](./api/bluesky-posting.md) - Social sharing

### For Reference
- [Existing Code](./reference/existing-code.md) - Current codebase reference
- [Glossary](./reference/glossary.md) - Terms and definitions

## Documentation Conventions

### Status Indicators
Each document uses these status indicators:
- 🔴 **Planned** - Not started
- 🟡 **In Progress** - Actively being worked on
- 🟢 **Implemented** - Complete and tested
- 🔵 **Documented** - Implemented with documentation

### Cross-References
Use relative links: `[Link Text](../path/to/file.md#optional-anchor)`

### LLM Optimization

This documentation is optimized for LLM consumption (Claude, Gemini, etc.):

**Self-Contained Files**: Each document includes necessary context at the top, so you don't need to read everything to understand a specific topic.

**Status Tracking**: Status indicators (🔴🟡🟢🔵) help quickly identify what's implemented vs planned.

**Cross-References**: Explicit linking helps navigate between related concepts. Each document includes a "Related Documents" section at the top.

**Code Examples**: Technical details include concrete code examples with real parameters, not just descriptions.

**Decision Rationale**: When documenting architectural choices, we explain "why" not just "what" - including alternatives considered and trade-offs.

**Searchable Terminology**: Consistent terminology throughout. See [glossary.md](./reference/glossary.md) for term definitions.

**File Size**: Individual files kept under 1000 lines. Longer topics split into sub-documents.

## Project Overview

Drydown is a fragrance review app built on AT Protocol / Bluesky that implements a unique three-stage rating system aligned with how fragrances develop over time:

1. **Stage 1 (Initial)**: Rate opening appeal, projection, and first impressions immediately
2. **Stage 2 (Heart)**: Rate heart notes after 2-4 hours when middle notes emerge
3. **Stage 3 (Final)**: Rate longevity, sillage, and complexity after 4+ hours

Users can customize rating weights, and the app calculates a final weighted score. Reviews can be shared directly to Bluesky with automatic formatting.

## Technology Stack

- **Frontend**: Preact 10.27.2 + TypeScript 5.9.3 + Vite 7.2.4
- **Authentication**: AT Protocol OAuth (`@atproto/oauth-client-browser`)
- **Data Storage**: AT Protocol Personal Data Server (via `@atproto/api`)
- **Social**: Bluesky feed posting

## Current Status

- ✅ OAuth authentication working
- ✅ Basic UI with login flow
- 🔴 Review features (planned)
- 🔴 Lexicon schemas (planned)
- 🔴 Bluesky posting (planned)

See [status.md](./status.md) for detailed progress tracking.

## Evolution Strategy

This documentation evolves as features are implemented:

1. **During Planning**: All features start with 🔴 Planned status
2. **During Implementation**: Update to 🟡 In Progress, add implementation notes
3. **After Completion**: Update to 🟢 Implemented, document any deviations
4. **After Documentation**: Update to 🔵 Documented with full details

The [status.md](./status.md) file tracks overall progress and serves as a quick reference for what's done vs what's next.

## Getting Started

**New to the project?** Start here:
1. Read [Product Features](./product/features.md) to understand what we're building
2. Review [Architecture Overview](./architecture/overview.md) for system design
3. Check [Implementation Roadmap](./implementation/overview.md) for development phases
4. See [Existing Code](./reference/existing-code.md) for what's already built

**Implementing a feature?** Start here:
1. Find the feature in [Product Features](./product/features.md)
2. Review related [Data Models](./data/data-models.md) and [Lexicon Schemas](./data/lexicon-schemas.md)
3. Check [Component Structure](./architecture/component-structure.md) for where it fits
4. Follow the relevant [Implementation Phase](./implementation/overview.md) guide
5. Update [status.md](./status.md) as you progress

**Working with AT Protocol?** Start here:
1. Review [AT Protocol Repo](./api/atproto-repo.md) for repository operations
2. Check [Lexicon Schemas](./data/lexicon-schemas.md) for record structures
3. See [Existing Code](./reference/existing-code.md#authentication) for OAuth examples

## Contributing to Documentation

When updating documentation:
- Update status indicators as features progress
- Add implementation notes and learnings
- Document deviations from the original plan
- Keep [status.md](./status.md) current
- Use meaningful commit messages: `docs: Add lexicon schema definitions`

## External Resources

- [AT Protocol Specification](https://atproto.com/specs/atp)
- [AT Protocol Lexicon Spec](https://atproto.com/specs/lexicon)
- [Bluesky Documentation](https://docs.bsky.app/)
- [Custom Schemas Guide](https://docs.bsky.app/docs/advanced-guides/custom-schemas)