Skip to content

Commit 679c299

Browse files
irangareddyirangareddy
committed
feat: detail feature documentation
1 parent 3755e49 commit 679c299

File tree

17 files changed

+2272
-156
lines changed

17 files changed

+2272
-156
lines changed

‎CLAUDE.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Repository Overview
6+
7+
Beetween is a **documentation-first product development platform** built with MkDocs. It serves as a collaborative hub for documenting the development of the Beet product - a vertical super-aggregator for Indian diaspora entertainment and cultural events.
8+
9+
**Tech Stack:**
10+
- Framework: MkDocs with Material theme
11+
- Language: Python (managed with Poetry)
12+
- Task Runner: Task (Taskfile)
13+
- Deployment: GitHub Pages
14+
15+
## Essential Commands
16+
17+
```bash
18+
# Initial setup
19+
task setup # Install dependencies and configure pre-commit hooks
20+
21+
# Development
22+
task serve # Start dev server at http://localhost:8000
23+
task serve-all # Start dev server accessible from all network interfaces
24+
25+
# Build and deploy
26+
task build # Build static documentation site
27+
task deploy # Deploy to GitHub Pages
28+
task clean # Clean build artifacts
29+
30+
# Feature management
31+
task create-feature FEATURE_NAME=feature-name # Create new feature documentation
32+
task list-features # List all available features
33+
34+
# Code quality
35+
task lint # Run black, isort, and flake8
36+
```
37+
38+
## Architecture and Structure
39+
40+
### Documentation-Centric Architecture
41+
42+
This is NOT a traditional application codebase - it's a documentation platform. The architecture follows a **feature-centric approach** where each product feature has its own documentation folder:
43+
44+
```
45+
docs/
46+
├── features/ # Feature-specific documentation
47+
│ ├── user-auth/ # Each feature gets its own folder
48+
│ ├── pay/ # with standardized structure
49+
│ ├── bites/
50+
│ ├── notifications/ # NEW: Smart notification system
51+
│ └── [feature]/
52+
├── software-3.0/ # NEW: AI/agent-ready architecture
53+
├── product/ # Product-level documentation
54+
├── decisions/ # Architecture and tech decisions
55+
└── resources/ # Team resources and guidelines
56+
```
57+
58+
### Key Files
59+
60+
- `mkdocs.yml`: Main configuration file for the documentation site
61+
- `Taskfile.yml`: Task automation definitions
62+
- `pyproject.toml`: Python dependencies and project metadata
63+
- `features/_template.md`: Template for new feature documentation
64+
65+
### Navigation Structure
66+
67+
The site navigation is defined in `mkdocs.yml`. When adding new features or pages, update the navigation structure there to ensure they appear in the site menu.
68+
69+
## Development Workflow
70+
71+
1. **Adding New Features**: Use `features/_template.md` to scaffold a new feature with the standard template
72+
2. **Local Development**: Always use `task serve` to preview changes locally before committing
73+
3. **Documentation Updates**: Focus on clarity and accessibility - avoid technical jargon where possible
74+
4. **No Code Blocks**: This documentation intentionally avoids code examples to stay accessible to all team members
75+
76+
## Important Conventions
77+
78+
- **Feature Documentation**: Each feature must have a single `feature.md` file as its source of truth
79+
- **Asset Organization**: Place images, wireframes, and diagrams in the feature's `assets/` subdirectories
80+
- **Owner Information**: Every document should have an owner and last updated date
81+
- **Markdown Extensions**: The project uses extensive markdown extensions (admonitions, tabs, mermaid diagrams) - see mkdocs.yml for full list
82+
83+
## Common Tasks
84+
85+
### Updating Existing Documentation
86+
1. Edit the relevant markdown files in `docs/`
87+
2. Preview changes with `task serve`
88+
3. Commit changes with descriptive messages
89+
90+
### Adding Images or Diagrams
91+
- Place images in the feature's `assets/` folder
92+
- Use relative paths in markdown: `![Description](assets/image.png)`
93+
- For diagrams, use Mermaid syntax (supported via plugin)
94+
95+
## Project-Specific Context
96+
97+
- **Product Focus**: Beet is a vertical super-aggregator for Indian diaspora entertainment
98+
- **Target Audience**: Internal team documentation (not end-user docs)
99+
- **Key Features**: User authentication, payments (Pay), content (Bites), events (Events), movie booking (Box Office), rewards (Bucks), notifications, user profiles
100+
- **Documentation Philosophy**: Single source of truth, self-contained features, clear ownership, minimal cognitive overhead
101+
102+
## Software 3.0 Integration
103+
104+
The project emphasizes building for the AI-driven future:
105+
- **Natural Language Interfaces**: Every feature accessible through conversational UI
106+
- **Agent-Ready Architecture**: APIs designed for autonomous AI agents
107+
- **Partnership Automation**: AI-driven partner matching and negotiation
108+
- **Predictive Experiences**: Proactive recommendations and notifications
109+
110+
## Partnership-Driven Growth Strategy
111+
112+
All features include comprehensive partnership strategies:
113+
- **Theater Chains**: Revenue sharing for movie bookings
114+
- **Restaurants**: Dining packages and exclusive discounts
115+
- **Event Organizers**: Community-driven event discovery
116+
- **Payment Partners**: Reward-funded cashback programs
117+
118+
## Testing
119+
120+
This documentation platform does not have automated tests. Quality is maintained through:
121+
- Pre-commit hooks for formatting
122+
- Manual review of documentation changes
123+
- Regular team reviews (weekly for features, monthly for roadmap)
124+
125+
## Deployment
126+
127+
The site automatically deploys to GitHub Pages when changes are pushed to the main branch. Manual deployment can be triggered with `task deploy`.

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -123,7 +123,7 @@ docs/
123123
│ ├── _template.md # Template for new features
124124
│ ├── user-auth/ # User Authentication Feature
125125
│ │ └── feature.md # Single source of truth for the feature
126-
│ ├── pay/ # Payment Processing Feature
126+
│ ├── pay/ # Pay Feature
127127
│ │ └── feature.md # Single source of truth for the feature
128128
│ └── [other-features]/ # Additional features
129129
│ └── feature.md # Single source of truth for each feature

‎Taskfile.yml‎

Lines changed: 0 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -61,100 +61,6 @@ tasks:
6161
- poetry update
6262
- poetry run pre-commit autoupdate
6363

64-
# Feature management tasks
65-
create-feature:
66-
desc: Create a new feature documentation structure
67-
vars:
68-
FEATURE_NAME: '{{default "new-feature" .FEATURE_NAME}}'
69-
requires:
70-
vars: [FEATURE_NAME]
71-
cmds:
72-
- mkdir -p docs/features/{{.FEATURE_NAME}}/assets/{wireframes,designs,diagrams}
73-
- |
74-
# Create the main feature documentation from template
75-
sed 's/{{\.FEATURE_NAME | title}}/{{.FEATURE_NAME | title}}/g; s/{{now | date "January 2, 2006"}}/'"$(date '+%B %d, %Y')"'/g' templates/feature-template.md > docs/features/{{.FEATURE_NAME}}/index.md
76-
- "echo ✅ Created feature documentation for: {{.FEATURE_NAME}}"
77-
- 'echo "📁 Location: docs/features/{{.FEATURE_NAME}}/"'
78-
- 'echo "📝 Edit: docs/features/{{.FEATURE_NAME}}/index.md"'
79-
- echo "📝 Remember to update mkdocs.yml navigation to include your new feature"
80-
81-
create-template:
82-
desc: Create the feature template file
83-
cmds:
84-
- mkdir -p templates
85-
- |
86-
cat > templates/feature-template.md << 'EOF'
87-
# {{.FEATURE_NAME | title}} Feature Overview
88-
89-
## 🎯 Feature Summary
90-
91-
**Status**: 📋 Planning
92-
**Priority**: [High/Medium/Low]
93-
**Owner**: [Team Member Name]
94-
**Target Release**: [Sprint/Date]
95-
96-
## What This Feature Does
97-
98-
[Describe what this feature does for users]
99-
100-
## User Stories
101-
102-
### As a [user type]
103-
- **I want to** [action]
104-
- **So that** [benefit]
105-
- **Acceptance Criteria:**
106-
- [ ] [Specific requirement 1]
107-
- [ ] [Specific requirement 2]
108-
109-
## Technical Requirements
110-
111-
- [ ] [Technical requirement 1]
112-
- [ ] [Technical requirement 2]
113-
114-
## Dependencies
115-
116-
- [ ] [Dependency 1]
117-
- [ ] [Dependency 2]
118-
119-
## Definition of Done
120-
121-
- [ ] Feature implemented
122-
- [ ] Tests written and passing
123-
- [ ] Documentation updated
124-
- [ ] Code reviewed
125-
- [ ] QA testing complete
126-
127-
---
128-
129-
**Document Owner**: [Name]
130-
**Created**: {{now | date "January 2, 2006"}}
131-
**Last Updated**: {{now | date "January 2, 2006"}}
132-
EOF
133-
- echo "✅ Feature template created at templates/feature-template.md"
134-
135-
update-feature-status:
136-
desc: Update feature status with current date
137-
vars:
138-
FEATURE_NAME: "{{.FEATURE_NAME}}"
139-
requires:
140-
vars: [FEATURE_NAME]
141-
cmds:
142-
- |
143-
FEATURE_PATH="docs/features/{{.FEATURE_NAME}}/status.md"
144-
if [ -f "$FEATURE_PATH" ]; then
145-
# Update the last updated date
146-
if grep -q "Last Updated" "$FEATURE_PATH"; then
147-
sed -i '' "s/Last Updated.*/Last Updated**: $(date '+%B %d, %Y')/" "$FEATURE_PATH"
148-
else
149-
echo "**Last Updated**: $(date '+%B %d, %Y')" >> "$FEATURE_PATH"
150-
fi
151-
echo "✅ Updated status for {{.FEATURE_NAME}}"
152-
else
153-
echo "❌ Feature {{.FEATURE_NAME}} not found"
154-
echo " Available features:"
155-
ls docs/features/ 2>/dev/null || echo " No features found"
156-
fi
157-
15864
list-features:
15965
desc: List all available features
16066
cmds:

‎docs/features/bites/feature.md‎

Lines changed: 105 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,110 @@
22

33
## 1. Why It Exists
44

5-
**Problem it solves**: How do we retain users in App. That's seriously a problem then we thought about a daily driver where people can back to app and swipe quick bites related to they know about important for Indian Dispora
5+
**Problem it solves**: Users miss out on entertainment opportunities because they're not actively searching. Traditional apps require intentional browsing, leading to low daily engagement and missed events that users would have loved.
66

7-
**Value proposition**: High Value information, Early bird tickets are linked here.
7+
**Value proposition**: Daily curated micro-content about entertainment, culture, and community events specifically for the Indian diaspora. Swipeable format makes discovery effortless and addictive, with exclusive early-bird deals creating urgency.
88

9-
**Strategic importance**: Core DAU important feature for retension.
9+
**Strategic importance**: Primary driver of Daily Active Users (DAU). Beet Bites creates a daily habit that naturally leads users to discover and purchase events, movies, and experiences through the platform.
10+
11+
## 2. Scope
12+
13+
### MVP (Current Phase)
14+
- 10-15 daily curated bites
15+
- Swipe interface (Tinder-style)
16+
- Categories: Movies, Events, Food, Culture
17+
- Early-bird ticket links
18+
- Save for later functionality
19+
20+
### Future Phases
21+
- **Phase 2**: Personalized feed, video bites, user-generated content
22+
- **Phase 3**: AI curation, sponsored bites, bite sharing, comments
23+
24+
## 3. Design Considerations
25+
26+
### User Experience
27+
- Load time: <1 second
28+
- Bite consumption: 5-10 seconds each
29+
- Daily session target: 3-5 minutes
30+
- Visual-first design with minimal text
31+
- Smooth swipe animations
32+
33+
### Technical Architecture
34+
- Pre-cached content for offline viewing
35+
- CDN for media delivery
36+
- ML-based content ranking
37+
- A/B testing framework for optimization
38+
39+
### Business Rules
40+
- New bites published daily at 8 AM local time
41+
- Bites expire after 48 hours
42+
- Maximum 20 bites per day
43+
- Early-bird deals valid for 24 hours
44+
- Saved bites stored for 30 days
45+
46+
## 4. Validation
47+
48+
### Success Metrics
49+
- **DAU increase**: 40% within 3 months
50+
- **Session frequency**: 1.5+ opens per day
51+
- **Bite engagement**: 80% swipe completion rate
52+
- **Conversion**: 15% click-through to events/movies
53+
- **Retention**: 60% weekly active users
54+
55+
### Technical Validation
56+
- Content loading performance testing
57+
- Swipe gesture responsiveness
58+
- Personalization algorithm accuracy
59+
- Push notification delivery rates
60+
61+
## 5. Risks & Edge Cases
62+
63+
### High Risk
64+
- **Content quality**: Poor curation reduces engagement
65+
- *Mitigation*: Editorial team, user feedback, ML optimization
66+
- **Information overload**: Too many bites overwhelm users
67+
- *Mitigation*: Daily limits, personalization, categories
68+
69+
### Medium Risk
70+
- **Stale content**: Same content reduces return visits
71+
- *Mitigation*: Strict freshness requirements, diverse sources
72+
- **Cultural misalignment**: Content doesn't resonate with diaspora
73+
- *Mitigation*: Community moderators, cultural consultants
74+
75+
### Edge Cases
76+
- **No relevant content**: Slow news days
77+
- *Handling*: Evergreen content bank, user-generated fills
78+
- **Regional differences**: Content relevance varies by location
79+
- *Handling*: Geo-targeted bites, local content partners
80+
81+
## Key User Flows
82+
83+
### Daily Bite Consumption
84+
1. User receives morning push notification
85+
2. Opens app to Beet Bites screen
86+
3. Swipes through daily bites
87+
4. Taps interesting bites for details
88+
5. Books early-bird tickets if interested
89+
6. Saves bites for later reference
90+
91+
### Discovering Through Bites
92+
1. User swipes through entertainment news
93+
2. Sees exclusive Bollywood movie premiere
94+
3. Taps for early-bird pricing
95+
4. Redirected to Box Office booking
96+
5. Completes purchase with Beet Pay
97+
98+
### Sharing Bites
99+
1. User finds interesting cultural event
100+
2. Long-presses to share options
101+
3. Shares to WhatsApp/social media
102+
4. Friends click link to view bite
103+
5. New users prompted to download app
104+
105+
---
106+
107+
**Status**: Not Started
108+
**Priority**: High
109+
**Owner**: TBD
110+
**Target Release**: Q2 2025
111+
**Last Updated**: June 20, 2025

0 commit comments

Comments
 (0)