HOO Technical Specification

Complete Developer Reference Guide

Document Overview

This document provides exhaustive technical specifications for building HOO - a household operations management platform. It covers system architecture, data models, API design, security requirements, infrastructure, and implementation guidelines without code snippets, focusing instead on concepts, patterns, and requirements that developers need to understand.

Target Audience: Backend Engineers, Frontend Engineers, Mobile Developers, DevOps Engineers, QA Engineers, Technical Leads

System Architecture
Technology Stack
Data Architecture
API Specification
Authentication & Authorization
Core Feature Modules
AI/ML Integration
Real-Time Systems
Notification System
Integration Architecture
Security Requirements
Performance Requirements
Infrastructure & DevOps
Testing Strategy
Monitoring & Observability
Mobile-Specific Requirements
Offline Support & Sync
Internationalization
Accessibility Requirements
Data Privacy & Compliance

1. System Architecture

1.1 High-Level Architecture

HOO follows a microservices-inspired modular monolith architecture, designed to start as a well-structured monolith that can be decomposed into microservices as scaling demands.

┌─────────────────────────────────────────────────────────────────────────┐
│                           CLIENT LAYER                                   │
├─────────────────┬─────────────────┬─────────────────┬───────────────────┤
│   iOS App       │   Android App   │   Web App       │   Admin Dashboard │
│   (Swift/RN)    │   (Kotlin/RN)   │   (Next.js)     │   (Next.js)       │
└────────┬────────┴────────┬────────┴────────┬────────┴─────────┬─────────┘
         │                 │                 │                   │
         └─────────────────┴────────┬────────┴───────────────────┘
                                    │
                           ┌────────▼────────┐
                           │   API Gateway   │
                           │   (Rate Limit,  │
                           │    Auth, Route) │
                           └────────┬────────┘
                                    │
         ┌──────────────────────────┼──────────────────────────┐
         │                          │                          │
    ┌────▼────┐              ┌──────▼──────┐            ┌──────▼──────┐
    │ GraphQL │              │   REST API  │            │  WebSocket  │
    │ Gateway │              │   Server    │            │   Server    │
    └────┬────┘              └──────┬──────┘            └──────┬──────┘
         │                          │                          │
         └──────────────────────────┼──────────────────────────┘
                                    │
                    ┌───────────────┼───────────────┐
                    │               │               │
              ┌─────▼─────┐   ┌─────▼─────┐   ┌─────▼─────┐
              │   Core    │   │    AI     │   │  Worker   │
              │  Service  │   │  Service  │   │  Service  │
              │  Layer    │   │  Layer    │   │  Layer    │
              └─────┬─────┘   └─────┬─────┘   └─────┬─────┘
                    │               │               │
         ┌──────────┴───────────────┴───────────────┴──────────┐
         │                    DATA LAYER                        │
         ├──────────┬──────────┬──────────┬──────────┬─────────┤
         │ Primary  │  Cache   │  Search  │  Queue   │  File   │
         │ Database │  Layer   │  Engine  │  System  │ Storage │
         │(Postgres)│ (Redis)  │(Elastic) │ (Redis)  │  (S3)   │
         └──────────┴──────────┴──────────┴──────────┴─────────┘

1.2 Service Layer Breakdown

Core Service Layer

Service	Responsibility	Dependencies
User Service	User management, profiles, preferences	Database, Cache
Household Service	Household CRUD, membership, settings	Database, User Service
Task Service	Task lifecycle, assignments, completion	Database, AI Service, Notification
Calendar Service	Events, scheduling, recurring items	Database, External Calendars
Grocery Service	Lists, items, store optimization	Database, AI Service
Briefing Service	Daily/evening summaries, insights	All core services, AI Service

AI Service Layer

Service	Responsibility	External Dependencies
NLP Service	Text parsing, intent extraction	OpenAI API
Voice Service	Speech-to-text, voice commands	Whisper API, Google Speech
Intelligence Service	Predictions, suggestions, patterns	Internal ML models
Email Parser	Extract tasks from forwarded emails	OpenAI API

Worker Service Layer

Worker	Responsibility	Trigger
Notification Worker	Push, email, SMS delivery	Queue-based
Sync Worker	External calendar sync	Scheduled + Event
Analytics Worker	Metrics calculation, aggregation	Scheduled
Cleanup Worker	Data archival, temp file cleanup	Scheduled

1.3 Communication Patterns

Pattern	Use Case	Implementation
Synchronous REST	Standard CRUD operations	HTTP/HTTPS
Synchronous GraphQL	Complex queries, mobile optimization	HTTP/HTTPS
Asynchronous Events	Cross-service communication	Redis Pub/Sub
Real-time Updates	Live task updates, partner sync	WebSocket
Background Jobs	Email parsing, notifications	Redis Queue

2. Technology Stack

2.1 Backend Stack

Layer	Technology	Rationale
Runtime	Node.js 20 LTS	Async I/O, JavaScript ecosystem, team familiarity
Framework	Next.js 14 (API Routes) + Express	Full-stack capability, API flexibility
Language	TypeScript 5.x	Type safety, better DX, fewer runtime errors
ORM	Prisma	Type-safe database access, migrations
Validation	Zod	Runtime type validation, schema-first
API Documentation	OpenAPI 3.0	Industry standard, auto-generation

2.2 Frontend Stack

Layer	Technology	Rationale
Framework	Next.js 14 (App Router)	SSR, RSC, file-based routing
Language	TypeScript 5.x	Consistency with backend
Styling	Tailwind CSS + Radix UI	Utility-first, accessible components
State Management	Zustand + React Query	Lightweight, server state handling
Forms	React Hook Form + Zod	Performance, validation
Animation	Framer Motion	Declarative animations

2.3 Mobile Stack

Approach	Technology	Target
Primary	React Native + Expo	iOS + Android from single codebase
Navigation	React Navigation 6	Native navigation patterns
State	Zustand + React Query	Shared patterns with web
Storage	MMKV	Fast local storage
Voice	Expo Speech, React Native Voice	Voice capture

2.4 Database Stack

Database	Purpose	Configuration
PostgreSQL 15	Primary data store	Supabase managed
Redis 7	Cache, sessions, queues, pub/sub	Upstash managed
Elasticsearch 8	Full-text search (future)	Elastic Cloud

2.5 Infrastructure Stack

Component	Technology	Provider
Hosting	Serverless + Edge	Vercel
Database	Managed PostgreSQL	Supabase
File Storage	Object Storage	Supabase Storage / AWS S3
CDN	Edge Network	Vercel Edge
Email	Transactional Email	Resend
SMS	SMS Gateway	MSG91 (India)
Push Notifications	Cross-platform push	Firebase Cloud Messaging
Monitoring	APM + Error Tracking	Sentry
Analytics	Product Analytics	PostHog
Logging	Centralized Logging	Axiom

2.6 External Service Dependencies

Service	Purpose	Fallback Strategy
OpenAI API	NLP, parsing, AI features	Queue + retry, graceful degradation
Google Calendar API	Calendar sync	Offline queue, manual sync
WhatsApp Business API	Notifications (future)	SMS fallback
Razorpay	Payments (India)	N/A (critical)

3. Data Architecture

3.1 Entity Relationship Overview

┌─────────────┐       ┌─────────────────┐       ┌─────────────┐
│    User     │──────<│ HouseholdMember │>──────│  Household  │
└──────┬──────┘       └─────────────────┘       └──────┬──────┘
       │                                                │
       │              ┌─────────────────┐               │
       └─────────────>│   UserSession   │               │
                      └─────────────────┘               │
                                                        │
       ┌────────────────────────────────────────────────┤
       │                    │                           │
       ▼                    ▼                           ▼
┌─────────────┐      ┌─────────────┐            ┌─────────────┐
│    Task     │      │   Event     │            │ GroceryList │
└──────┬──────┘      └─────────────┘            └──────┬──────┘
       │                                               │
       ▼                                               ▼
┌─────────────┐                                 ┌─────────────┐
│  TaskLog    │                                 │ GroceryItem │
└─────────────┘                                 └─────────────┘

3.2 Core Data Models

User Model

Field	Type	Constraints	Description
id	UUID	Primary Key	Unique identifier
email	String	Unique, Indexed	User email
phone	String	Unique, Nullable	Phone number (E.164 format)
name	String	Required	Display name
avatar_url	String	Nullable	Profile picture URL
timezone	String	Default: "Asia/Kolkata"	User timezone
language	Enum	Default: "en"	Preferred language
notification_preferences	JSONB	Default: {}	Notification settings
onboarding_completed	Boolean	Default: false	Onboarding status
created_at	Timestamp	Auto	Creation time
updated_at	Timestamp	Auto	Last update time
deleted_at	Timestamp	Nullable	Soft delete

Household Model

Field	Type	Constraints	Description
id	UUID	Primary Key	Unique identifier
name	String	Required	Household name
slug	String	Unique	URL-friendly identifier
settings	JSONB	Default: {}	Household settings
subscription_tier	Enum	Default: "free"	Subscription level
subscription_expires_at	Timestamp	Nullable	Subscription expiry
created_at	Timestamp	Auto	Creation time
updated_at	Timestamp	Auto	Last update time

HouseholdMember Model (Junction)

Field	Type	Constraints	Description
id	UUID	Primary Key	Unique identifier
household_id	UUID	Foreign Key	Reference to household
user_id	UUID	Foreign Key	Reference to user
role	Enum	Default: "member"	Role: owner, admin, member
nickname	String	Nullable	Display name within household
joined_at	Timestamp	Auto	Join time
invited_by	UUID	Foreign Key, Nullable	Who invited this member
invitation_status	Enum	Default: "pending"	pending, accepted, declined

Task Model

Field	Type	Constraints	Description
id	UUID	Primary Key	Unique identifier
household_id	UUID	Foreign Key, Indexed	Parent household
title	String	Required, Max 500	Task title
description	Text	Nullable	Extended description
context	Text	Nullable	AI-extracted context
status	Enum	Indexed	pending, in_progress, completed, cancelled
priority	Enum	Default: "medium"	low, medium, high, urgent
category	Enum	Indexed	home, kids, finance, health, etc.
assigned_to	UUID	Foreign Key, Nullable	Assigned user
created_by	UUID	Foreign Key	Creator user
due_date	Timestamp	Nullable, Indexed	When task is due
due_time	Time	Nullable	Specific time if applicable
reminder_at	Timestamp	Nullable	When to remind
completed_at	Timestamp	Nullable	Completion time
completed_by	UUID	Foreign Key, Nullable	Who completed
recurrence_rule	String	Nullable	iCal RRULE format
recurrence_parent_id	UUID	Foreign Key, Nullable	Parent recurring task
source	Enum	Default: "manual"	manual, voice, email, calendar
source_metadata	JSONB	Nullable	Source-specific data
attachments	JSONB	Default: []	File references
created_at	Timestamp	Auto	Creation time
updated_at	Timestamp	Auto	Last update time
deleted_at	Timestamp	Nullable	Soft delete

Event Model

Field	Type	Constraints	Description
id	UUID	Primary Key	Unique identifier
household_id	UUID	Foreign Key, Indexed	Parent household
title	String	Required	Event title
description	Text	Nullable	Event description
location	String	Nullable	Event location
start_time	Timestamp	Required, Indexed	Event start
end_time	Timestamp	Required	Event end
all_day	Boolean	Default: false	All-day event flag
attendees	UUID[]	Default: []	Household members attending
external_id	String	Nullable, Indexed	External calendar event ID
external_source	Enum	Nullable	google, apple, outlook
recurrence_rule	String	Nullable	iCal RRULE format
reminders	JSONB	Default: []	Reminder configurations
created_by	UUID	Foreign Key	Creator
created_at	Timestamp	Auto	Creation time
updated_at	Timestamp	Auto	Last update time

GroceryList Model

Field	Type	Constraints	Description
id	UUID	Primary Key	Unique identifier
household_id	UUID	Foreign Key	Parent household
name	String	Default: "Grocery List"	List name
store	String	Nullable	Target store
status	Enum	Default: "active"	active, shopping, completed
shopping_started_at	Timestamp	Nullable	When shopping started
completed_at	Timestamp	Nullable	When completed
created_by	UUID	Foreign Key	Creator
created_at	Timestamp	Auto	Creation time

GroceryItem Model

Field	Type	Constraints	Description
id	UUID	Primary Key	Unique identifier
list_id	UUID	Foreign Key, Indexed	Parent list
name	String	Required	Item name
quantity	String	Nullable	Quantity description
category	String	Nullable	Aisle/category
notes	Text	Nullable	Additional notes
checked	Boolean	Default: false	Purchased flag
checked_by	UUID	Foreign Key, Nullable	Who checked
checked_at	Timestamp	Nullable	When checked
added_by	UUID	Foreign Key	Who added
position	Integer	Default: 0	Sort order
created_at	Timestamp	Auto	Creation time

3.3 Activity/Audit Log Model

Field	Type	Description
id	UUID	Primary Key
household_id	UUID	Household reference
user_id	UUID	Acting user
entity_type	Enum	task, event, grocery, household, etc.
entity_id	UUID	Reference to entity
action	Enum	created, updated, deleted, completed, assigned, etc.
changes	JSONB	Before/after values
metadata	JSONB	Additional context
created_at	Timestamp	When action occurred

3.4 Database Indexes Strategy

Table	Index	Type	Purpose
tasks	household_id, status	Composite B-tree	List active tasks
tasks	household_id, due_date	Composite B-tree	Tasks by date
tasks	assigned_to, status	Composite B-tree	User's tasks
tasks	created_at	B-tree DESC	Recent tasks
tasks	title, description	GIN (full-text)	Search
events	household_id, start_time	Composite B-tree	Events by date
events	external_id	B-tree	External sync
activity_logs	household_id, created_at	Composite B-tree DESC	Activity feed
users	email	Unique B-tree	Login lookup
users	phone	Unique B-tree	Phone lookup

3.5 Data Partitioning Strategy

For tables expected to grow large (activity_logs, tasks):

Table	Partition Key	Strategy	Retention
activity_logs	created_at	Monthly range	12 months hot, archive older
tasks (historical)	completed_at	Quarterly range	Move to cold storage after 2 years

4. API Specification

4.1 API Design Principles

RESTful Design: Follow REST conventions for resource-based endpoints
Consistent Response Format: All responses follow standard envelope
Versioning: URL-based versioning (v1, v2)
Pagination: Cursor-based pagination for lists
Filtering: Query parameter-based filtering
Sorting: Standardized sort parameter
Field Selection: Optional sparse fieldsets
Error Handling: Consistent error response format

4.2 Response Envelope Format

Success Response:

{
  "success": true,
  "data": { ... },
  "meta": {
    "timestamp": "2026-01-20T10:30:00Z",
    "request_id": "req_abc123"
  }
}

List Response with Pagination:

{
  "success": true,
  "data": [ ... ],
  "pagination": {
    "cursor": "eyJpZCI6IjEyMyJ9",
    "has_more": true,
    "total_count": 150
  },
  "meta": { ... }
}

Error Response:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      { "field": "email", "message": "Invalid email format" }
    ]
  },
  "meta": { ... }
}

4.3 Core API Endpoints

Authentication Endpoints

Method	Endpoint	Description	Auth
POST	/v1/auth/register	Register new user	None
POST	/v1/auth/login	Login with email/password	None
POST	/v1/auth/login/otp/request	Request OTP login	None
POST	/v1/auth/login/otp/verify	Verify OTP and login	None
POST	/v1/auth/login/google	Google OAuth login	None
POST	/v1/auth/login/apple	Apple OAuth login	None
POST	/v1/auth/refresh	Refresh access token	Refresh Token
POST	/v1/auth/logout	Logout current session	Access Token
POST	/v1/auth/logout/all	Logout all sessions	Access Token
POST	/v1/auth/password/reset/request	Request password reset	None
POST	/v1/auth/password/reset/confirm	Confirm password reset	Reset Token

User Endpoints

Method	Endpoint	Description	Auth
GET	/v1/users/me	Get current user profile	Required
PATCH	/v1/users/me	Update current user profile	Required
DELETE	/v1/users/me	Delete user account	Required
GET	/v1/users/me/preferences	Get user preferences	Required
PATCH	/v1/users/me/preferences	Update preferences	Required
POST	/v1/users/me/avatar	Upload avatar	Required
DELETE	/v1/users/me/avatar	Remove avatar	Required

Household Endpoints

Method	Endpoint	Description	Auth
POST	/v1/households	Create new household	Required
GET	/v1/households	List user's households	Required
GET	/v1/households/:id	Get household details	Member
PATCH	/v1/households/:id	Update household	Admin
DELETE	/v1/households/:id	Delete household	Owner
GET	/v1/households/:id/members	List household members	Member
POST	/v1/households/:id/members/invite	Invite member	Admin
DELETE	/v1/households/:id/members/:userId	Remove member	Admin
PATCH	/v1/households/:id/members/:userId	Update member role	Owner
POST	/v1/households/:id/leave	Leave household	Member

Task Endpoints

Method	Endpoint	Description	Auth
POST	/v1/households/:id/tasks	Create task	Member
GET	/v1/households/:id/tasks	List tasks	Member
GET	/v1/households/:id/tasks/:taskId	Get task details	Member
PATCH	/v1/households/:id/tasks/:taskId	Update task	Member
DELETE	/v1/households/:id/tasks/:taskId	Delete task	Member
POST	/v1/households/:id/tasks/:taskId/complete	Mark complete	Member
POST	/v1/households/:id/tasks/:taskId/assign	Assign task	Member
POST	/v1/households/:id/tasks/:taskId/unassign	Unassign task	Member
GET	/v1/households/:id/tasks/today	Get today's tasks	Member
GET	/v1/households/:id/tasks/upcoming	Get upcoming tasks	Member
GET	/v1/households/:id/tasks/overdue	Get overdue tasks	Member

Event Endpoints

Method	Endpoint	Description	Auth
POST	/v1/households/:id/events	Create event	Member
GET	/v1/households/:id/events	List events	Member
GET	/v1/households/:id/events/:eventId	Get event details	Member
PATCH	/v1/households/:id/events/:eventId	Update event	Member
DELETE	/v1/households/:id/events/:eventId	Delete event	Member
GET	/v1/households/:id/events/range	Get events in date range	Member

Grocery Endpoints

Method	Endpoint	Description	Auth
POST	/v1/households/:id/grocery-lists	Create grocery list	Member
GET	/v1/households/:id/grocery-lists	List grocery lists	Member
GET	/v1/households/:id/grocery-lists/:listId	Get list with items	Member
PATCH	/v1/households/:id/grocery-lists/:listId	Update list	Member
DELETE	/v1/households/:id/grocery-lists/:listId	Delete list	Member
POST	/v1/households/:id/grocery-lists/:listId/items	Add item	Member
PATCH	/v1/households/:id/grocery-lists/:listId/items/:itemId	Update item	Member
DELETE	/v1/households/:id/grocery-lists/:listId/items/:itemId	Delete item	Member
POST	/v1/households/:id/grocery-lists/:listId/items/:itemId/check	Check item	Member
POST	/v1/households/:id/grocery-lists/:listId/start-shopping	Start shopping mode	Member
POST	/v1/households/:id/grocery-lists/:listId/complete	Complete shopping	Member

AI/Capture Endpoints

Method	Endpoint	Description	Auth
POST	/v1/capture/text	Parse text into task(s)	Required
POST	/v1/capture/voice	Process voice recording	Required
POST	/v1/capture/email	Process forwarded email	Required
POST	/v1/capture/image	Extract text from image	Required
GET	/v1/suggestions/tasks	Get AI task suggestions	Required

Briefing Endpoints

Method	Endpoint	Description	Auth
GET	/v1/households/:id/briefings/morning	Get morning briefing	Member
GET	/v1/households/:id/briefings/evening	Get evening briefing	Member
GET	/v1/households/:id/briefings/weekly	Get weekly summary	Member
GET	/v1/households/:id/stats	Get household statistics	Member
GET	/v1/households/:id/load-balance	Get load balance metrics	Member

4.4 Query Parameters

Pagination:

cursor: Opaque cursor for next page
limit: Number of items (default: 20, max: 100)

Filtering (Tasks):

status: Filter by status (pending, completed, etc.)
category: Filter by category
assigned_to: Filter by assignee (user ID or "me" or "unassigned")
due_date_from: Filter by due date start
due_date_to: Filter by due date end
priority: Filter by priority

Sorting:

sort: Field to sort by (created_at, due_date, priority)
order: Sort order (asc, desc)

Search:

q: Full-text search query

4.5 Rate Limiting

Tier	Limit	Window	Scope
Anonymous	20 requests	1 minute	IP
Free User	100 requests	1 minute	User
Paid User	500 requests	1 minute	User
AI Endpoints	20 requests	1 minute	User
File Upload	10 requests	1 minute	User

Rate limit headers returned:

X-RateLimit-Limit: Request limit
X-RateLimit-Remaining: Remaining requests
X-RateLimit-Reset: Reset timestamp

5. Authentication & Authorization

5.1 Authentication Methods

Method	Use Case	Implementation
Email + Password	Traditional login	bcrypt hashing, min 8 chars
OTP (SMS/Email)	Passwordless login	6-digit, 5-min expiry
Google OAuth	Social login	OAuth 2.0 PKCE flow
Apple Sign-In	iOS social login	OAuth 2.0 with JWT
Magic Link	Email-based login	Token in URL, 15-min expiry

5.2 Token Strategy

Token Type	Format	Expiry	Storage
Access Token	JWT	15 minutes	Memory (client)
Refresh Token	Opaque UUID	30 days	HttpOnly cookie + DB
Session Token	Opaque UUID	30 days	DB reference

JWT Access Token Claims:

sub: User ID
email: User email
households: Array of household IDs with roles
iat: Issued at
exp: Expiration
jti: Unique token ID

5.3 Session Management

Aspect	Specification
Concurrent Sessions	Unlimited (configurable per user)
Session Tracking	Device fingerprint, IP, user agent
Session Revocation	Individual or all sessions
Activity Tracking	Last active timestamp per session
Security Events	Log login, logout, password change, new device

5.4 Authorization Model

Role-Based Access Control (RBAC):

Role	Household Permissions
Owner	All permissions, delete household, transfer ownership
Admin	Manage members, manage settings, all content permissions
Member	Create/edit/delete own content, complete any task

Resource-Level Permissions:

Resource	Create	Read	Update	Delete
Task	Member	Member	Member (own) / Admin (all)	Member (own) / Admin (all)
Event	Member	Member	Creator / Admin	Creator / Admin
Grocery List	Member	Member	Member	Creator / Admin
Household Settings	-	Member	Admin	Owner
Members	Admin (invite)	Member	Owner	Admin

5.5 Security Headers

Header	Value	Purpose
`Strict-Transport-Security`	max-age=31536000; includeSubDomains	Force HTTPS
`X-Content-Type-Options`	nosniff	Prevent MIME sniffing
`X-Frame-Options`	DENY	Prevent clickjacking
`X-XSS-Protection`	1; mode=block	XSS protection
`Content-Security-Policy`	[strict policy]	Script/resource restrictions
`Referrer-Policy`	strict-origin-when-cross-origin	Referrer control

6. Core Feature Modules

6.1 Task Management Module

Task Lifecycle States

                    ┌──────────────┐
                    │   Created    │
                    └──────┬───────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
              ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │ Pending  │ │ Assigned │ │ Scheduled│
        └────┬─────┘ └────┬─────┘ └────┬─────┘
             │            │            │
             └────────────┼────────────┘
                          │
                          ▼
                    ┌──────────┐
                    │In Progress│
                    └────┬─────┘
                         │
            ┌────────────┼────────────┐
            │            │            │
            ▼            ▼            ▼
      ┌──────────┐ ┌──────────┐ ┌──────────┐
      │Completed │ │ Cancelled│ │ Deferred │
      └──────────┘ └──────────┘ └──────────┘

Task Categories

Category	Icon	Description
home	🏠	General household tasks
kids	👶	Child-related tasks
school	📚	School/education tasks
health	🏥	Health/medical tasks
finance	💰	Financial tasks
shopping	🛒	Shopping (non-grocery)
maintenance	🔧	Home maintenance
social	👥	Social obligations
work	💼	Work-related home tasks
pets	🐾	Pet care tasks
other	📋	Uncategorized

Recurrence Support

Frequency: Daily, Weekly, Bi-weekly, Monthly, Yearly, Custom
Format: iCal RRULE specification
Instance Generation: Generate instances up to 60 days ahead
Modification: Modify single instance vs. all future instances
Completion: Complete instance, auto-generate next occurrence

6.2 Calendar Module

Calendar Event Types

Type	Characteristics
Single Event	One-time occurrence
Recurring Event	Repeating with RRULE
All-Day Event	No specific time
Multi-Day Event	Spans multiple days
Synced Event	From external calendar (read-only)

External Calendar Integration

Provider	Sync Type	Features
Google Calendar	Two-way	Full CRUD, push notifications
Apple Calendar	One-way (read)	Import events
Outlook	One-way (read)	Import events

Calendar Sync Logic

Initial Sync: Import all events from past 30 days to future 365 days
Incremental Sync: Use provider webhooks/push notifications
Conflict Resolution: External calendar is source of truth for synced events
Sync Frequency: Real-time via webhooks, fallback polling every 15 minutes

6.3 Grocery Module

Grocery List States

Active → Shopping → Completed
                ↓
            Archived

Smart Categorization

Auto-categorize: Use AI to assign items to store sections
Store Memory: Learn store layouts from user behavior
Quantity Parsing: "2 dozen eggs" → quantity: "2 dozen", item: "eggs"

List Features

Feature	Description
Multiple Lists	Support multiple concurrent lists
List Templates	Save and reuse common lists
Item Suggestions	Based on purchase history
Voice Add	"Add milk and bread to grocery list"
Sharing	Real-time sync with partner in store

6.4 Briefing Module

Morning Briefing Components

Component	Data Source	Priority
Today's tasks	Task service	P0
Today's events	Calendar service	P0
Overdue items	Task service	P0
Partner's schedule	Calendar service	P1
Weather (if affects plans)	External API	P2
Household status summary	Analytics	P1

Evening Briefing Components

Component	Data Source	Priority
Today's completions	Task service	P0
Partner's contributions	Activity log	P0
Tomorrow preview	Task/Calendar	P0
Week ahead summary	Task/Calendar	P1
Load balance status	Analytics	P1

Briefing Generation Logic

Trigger at configured time (default: 7am morning, 7pm evening)
Aggregate data from all relevant services
Apply AI summarization for natural language
Cache generated briefing for 1 hour
Push notification with summary

6.5 Power Hour Module

Power Hour Flow

Initiation: User selects time duration (15/30/60 min) and focus area
Task Queue: System generates prioritized task queue
Execution Mode: Focused interface showing current task
Progress Tracking: Timer, completion count, remaining tasks
Completion: Summary of accomplished tasks, celebration

Task Prioritization Algorithm

Score = (Priority Weight × 3) +
        (Due Date Urgency × 2) +
        (Estimated Duration Fit × 1) +
        (Category Match × 1)

7. AI/ML Integration

7.1 Natural Language Processing

Text Parsing Pipeline

Input Text
    │
    ▼
┌────────────────┐
│ Pre-processing │  ← Normalize, clean, handle Hindi/English
└───────┬────────┘
        │
        ▼
┌────────────────┐
│ Intent Detection│  ← Identify: create task, add grocery, schedule event
└───────┬────────┘
        │
        ▼
┌────────────────┐
│ Entity Extraction│  ← Date, time, person, item, location
└───────┬────────┘
        │
        ▼
┌────────────────┐
│ Context Enrichment│  ← Add inferred context
└───────┬────────┘
        │
        ▼
Structured Output

Entity Types to Extract

Entity	Examples	Pattern
Date	"tomorrow", "next Tuesday", "15th Jan"	Temporal expressions
Time	"3pm", "morning", "after lunch"	Time expressions
Person	"for Emma", "remind Rahul"	Named entities
Location	"at school", "from BigBasket"	Location references
Quantity	"2 packets", "500ml"	Numeric + unit
Priority	"urgent", "when you get time"	Urgency markers
Recurrence	"every week", "daily"	Repeat patterns

OpenAI Integration Specification

Model Selection:

Use Case	Model	Rationale
Task parsing	GPT-4o-mini	Fast, accurate, cost-effective
Email parsing	GPT-4o	Complex document understanding
Summarization	GPT-4o-mini	Quick summaries
Voice transcription	Whisper-1	Best accuracy for Indian accents

Prompt Engineering Guidelines:

Use structured output format (JSON mode)
Include Indian context examples in few-shot prompts
Handle code-switching (Hindi-English mix)
Specify timezone context (IST)
Return confidence scores for extracted entities

Error Handling:

Retry with exponential backoff (3 attempts)
Fallback to simpler parsing if API fails
Queue for later processing if persistent failure
Never block user flow on AI failure

7.2 Voice Processing

Voice Capture Flow

User Speaks → Recording → Upload → Whisper API → Text → NLP Pipeline → Task

Voice Requirements

Aspect	Specification
Format	WAV, M4A, MP3, WebM
Max Duration	60 seconds
Sample Rate	16kHz minimum
Language Support	English, Hindi, Hinglish
Noise Tolerance	Handle background noise (home environment)

Whisper Configuration

Model: whisper-1
Language hint: Based on user preference
Response format: JSON with timestamps
Post-processing: Punctuation restoration, capitalization

7.3 Email Parsing

Email Forwarding System

Dedicated Inbox: User forwards to tasks@hoo.app or {user-token}@tasks.hoo.app
Email Receipt: Webhook from email provider (SendGrid/Resend)
Parsing: Extract sender, subject, body, attachments
AI Processing: Identify actionable items
Task Creation: Create tasks with original email as context
User Review: Notification to confirm/edit extracted tasks

Extractable Content Types

Email Type	Extraction
School newsletter	Dates, deadlines, events
Appointment confirmation	Date, time, location, doctor
Bill/receipt	Due date, amount, vendor
Invitation	Event date, RSVP deadline
Delivery confirmation	Expected date, tracking

7.4 Predictive Features

Suggestion Engine Inputs

Historical task completion patterns
Time of day / day of week patterns
Seasonal patterns (festivals, school year)
Partner availability patterns
Weather conditions (for outdoor tasks)

Suggestion Types

Type	Trigger	Example
Recurring Task	Similar task completed regularly	"Add 'Buy milk' - you do this every Sunday"
Upcoming Need	Based on last completion	"Car service due - last done 5 months ago"
Weather-Based	Weather + outdoor task	"Good weather tomorrow - garden work?"
Load Balance	Imbalanced distribution	"Partner is light this week - suggest reassignment?"

8. Real-Time Systems

8.1 WebSocket Architecture

Connection Management

Client Connect → Authenticate → Subscribe to Channels → Receive Events
                                          │
                                          ▼
                            ┌──────────────────────────┐
                            │     Channel Types        │
                            ├──────────────────────────┤
                            │ household:{id}           │  ← All household updates
                            │ household:{id}:tasks     │  ← Task updates only
                            │ household:{id}:presence  │  ← Member online status
                            │ user:{id}                │  ← Personal notifications
                            └──────────────────────────┘

Event Types

Event	Payload	Trigger
`task.created`	Full task object	New task created
`task.updated`	Task ID + changed fields	Task modified
`task.completed`	Task ID, completed_by, timestamp	Task completed
`task.deleted`	Task ID	Task deleted
`event.created`	Full event object	New calendar event
`event.updated`	Event ID + changed fields	Event modified
`grocery.item_added`	List ID, item object	Item added to list
`grocery.item_checked`	List ID, item ID, checked_by	Item checked off
`member.joined`	Member details	New member accepted invite
`member.presence`	User ID, status (online/offline)	Presence change
`typing`	User ID, entity type, entity ID	User is typing/editing

WebSocket Message Format

{
  "type": "event",
  "event": "task.created",
  "channel": "household:abc123",
  "data": { ... },
  "timestamp": "2026-01-20T10:30:00Z",
  "sender_id": "user_xyz"
}

8.2 Presence System

Presence States

State	Description	Display
`online`	Active in app (last ping < 30s)	Green dot
`away`	App open but inactive (30s - 5m)	Yellow dot
`offline`	Not connected	No indicator

Presence Update Frequency

Client ping: Every 25 seconds
Server timeout: 35 seconds without ping
State broadcast: Immediate on change

8.3 Optimistic Updates

Client-Side Optimistic Update Flow

User action triggers local state update immediately
API request sent in background
On success: Confirm local state
On failure: Rollback local state, show error

Conflict Resolution

Server timestamp is source of truth
Last-write-wins for simple fields
Merge strategy for arrays (add both, dedupe)
Show conflict UI for significant conflicts

9. Notification System

9.1 Notification Channels

Channel	Use Cases	Provider
Push (Mobile)	Real-time alerts, reminders	Firebase Cloud Messaging
Push (Web)	Browser notifications	Web Push API
Email	Summaries, digests, invitations	Resend
SMS	Critical alerts, OTP	MSG91
In-App	All notifications, history	Native

9.2 Notification Types

Type	Channels	Batching	User Configurable
Task assigned	Push, In-App	Immediate	Yes
Task completed	Push, In-App	Batch (5 min)	Yes
Task reminder	Push, In-App	Immediate	Yes
Event reminder	Push, In-App	Immediate	Yes
Partner activity	Push, In-App	Batch (15 min)	Yes
Morning briefing	Push, In-App	Scheduled	Yes
Evening briefing	Push, In-App	Scheduled	Yes
Weekly summary	Email, In-App	Scheduled	Yes
Household invitation	Push, Email, SMS	Immediate	No
Payment reminder	Push, Email	Immediate	No
Security alert	Push, Email, SMS	Immediate	No

9.3 Notification Preferences Schema

{
  "channels": {
    "push": true,
    "email": true,
    "sms": false
  },
  "types": {
    "task_assigned": { "push": true, "email": false },
    "task_completed": { "push": true, "email": false },
    "briefings": { "push": true, "email": true },
    "partner_activity": { "push": true, "email": false }
  },
  "quiet_hours": {
    "enabled": true,
    "start": "22:00",
    "end": "07:00",
    "timezone": "Asia/Kolkata"
  },
  "briefing_times": {
    "morning": "07:00",
    "evening": "19:00"
  }
}

9.4 Notification Queue Architecture

Event Occurs → Notification Service → Queue (Redis)
                                          │
                    ┌─────────────────────┼─────────────────────┐
                    │                     │                     │
                    ▼                     ▼                     ▼
            ┌───────────────┐     ┌───────────────┐     ┌───────────────┐
            │ Push Worker   │     │ Email Worker  │     │  SMS Worker   │
            └───────┬───────┘     └───────┬───────┘     └───────┬───────┘
                    │                     │                     │
                    ▼                     ▼                     ▼
                   FCM               Resend API             MSG91 API

9.5 Push Notification Payload

iOS (APNs via FCM):

{
  "notification": {
    "title": "Task Completed",
    "body": "Rahul completed 'Buy groceries'",
    "sound": "default",
    "badge": 3
  },
  "data": {
    "type": "task.completed",
    "task_id": "task_abc123",
    "household_id": "hh_xyz789",
    "action_url": "hoo://tasks/task_abc123"
  },
  "apns": {
    "headers": {
      "apns-priority": "10"
    }
  }
}

Android (FCM):

{
  "notification": {
    "title": "Task Completed",
    "body": "Rahul completed 'Buy groceries'",
    "channel_id": "task_updates"
  },
  "data": {
    "type": "task.completed",
    "task_id": "task_abc123",
    "household_id": "hh_xyz789",
    "click_action": "OPEN_TASK"
  },
  "android": {
    "priority": "high"
  }
}

10. Integration Architecture

10.1 Calendar Integration

Google Calendar Integration

OAuth Scopes Required:

https://www.googleapis.com/auth/calendar.readonly (read events)
https://www.googleapis.com/auth/calendar.events (write events)

Sync Implementation:

Aspect	Specification
Initial sync	Full sync of primary calendar
Incremental sync	Use `syncToken` for delta sync
Push notifications	Google Calendar push notifications to webhook
Webhook URL	`/webhooks/google-calendar`
Retry strategy	Exponential backoff, max 5 retries

Apple Calendar (CalDAV)

Read-only sync via CalDAV protocol
Polling-based (every 30 minutes)
Support for iCloud and Exchange

10.2 Payment Integration (Razorpay)

Subscription Flow

User selects plan → Create Razorpay subscription →
Redirect to Razorpay checkout → Payment confirmation webhook →
Update subscription status → Grant premium access

Webhook Events to Handle:

Event	Action
`subscription.activated`	Grant premium access
`subscription.charged`	Record payment, extend subscription
`subscription.pending`	Mark as pending, notify user
`subscription.halted`	Revoke premium, notify user
`subscription.cancelled`	Handle cancellation, offer retention
`payment.failed`	Notify user, retry logic

Subscription Tiers:

Plan ID	Price (INR)	Billing Cycle
`hoo_plus_monthly`	199	Monthly
`hoo_plus_yearly`	1999	Yearly
`hoo_premium_monthly`	349	Monthly
`hoo_premium_yearly`	3499	Yearly
`hoo_family_monthly`	499	Monthly
`hoo_family_yearly`	4999	Yearly

10.3 WhatsApp Integration (Future)

WhatsApp Business API Use Cases

Use Case	Message Type
Task reminders	Template message
Partner invitation	Template message
Briefing delivery	Template message
Quick task capture	Incoming message parsing

10.4 Webhook Security

Signature Verification:

Each provider sends signature in header
Verify HMAC signature before processing
Reject requests with invalid signatures
Log all webhook events for debugging

Idempotency:

Store webhook event IDs
Skip processing for duplicate events
Use database transactions for consistency

11. Security Requirements

11.1 Data Encryption

Data State	Encryption
In Transit	TLS 1.3, HTTPS only
At Rest (Database)	AES-256 (provider-managed)
At Rest (Files)	AES-256 (S3 server-side encryption)
Sensitive Fields	Application-level encryption (passwords, tokens)

11.2 Password Requirements

Requirement	Specification
Minimum length	8 characters
Complexity	At least one letter and one number
Hashing	bcrypt with cost factor 12
History	Prevent reuse of last 5 passwords
Breach check	Integrate with HaveIBeenPwned API

11.3 Input Validation

Layer	Validation Type
Client	Format validation, UX feedback
API Gateway	Schema validation (Zod)
Service Layer	Business rule validation
Database	Constraints, type enforcement

Sanitization Rules:

Escape HTML in all user inputs
Validate URLs against allowlist
Sanitize file names for uploads
Validate JSON structure depth

11.4 API Security

Measure	Implementation
Rate Limiting	Redis-based sliding window
Request Signing	Optional HMAC for sensitive endpoints
IP Allowlisting	Configurable per API key
Request Size Limit	10MB max body size
SQL Injection	Parameterized queries (Prisma)
XSS Prevention	Content-Type headers, CSP
CSRF Protection	SameSite cookies, CSRF tokens

11.5 Secrets Management

Secret Type	Storage
Environment variables	Vercel encrypted env vars
API keys	Environment variables
Database credentials	Environment variables
Encryption keys	Environment variables + rotation policy
User secrets	Database (encrypted)

11.6 Security Logging

Events to Log:

Authentication attempts (success/failure)
Authorization failures
Password changes
Session creation/destruction
Sensitive data access
Admin actions
Webhook events
API errors

Log Format:

Timestamp (ISO 8601)
Event type
User ID (if authenticated)
IP address
User agent
Request ID
Result (success/failure)
Additional context

12. Performance Requirements

12.1 Response Time Targets

Endpoint Type	P50	P95	P99
Read (simple)	50ms	150ms	300ms
Read (complex)	100ms	300ms	500ms
Write	100ms	250ms	500ms
AI/Parse	500ms	1500ms	3000ms
File upload	200ms	1000ms	2000ms

12.2 Throughput Targets

Metric	Target
Concurrent users	10,000
Requests per second	1,000
WebSocket connections	50,000
Background jobs per minute	5,000

12.3 Caching Strategy

Cache Layer	Purpose	TTL
CDN (Vercel Edge)	Static assets, API responses	1 hour - 1 year
Redis	Session data, computed results	5 min - 24 hours
Application	Frequently accessed data	Request-scoped
Database	Query results	Connection pool

Cache Invalidation:

Event-driven invalidation on writes
Time-based expiration
Manual invalidation API for admin

12.4 Database Optimization

Query Optimization:

Use query analyzer for slow queries (>100ms)
Create indexes based on query patterns
Use connection pooling (PgBouncer)
Implement read replicas for heavy reads (future)

Connection Pooling:

Pool size: 20 connections per instance
Idle timeout: 10 seconds
Connection timeout: 5 seconds

12.5 File Handling

File Type	Max Size	Processing
Avatar image	5MB	Resize to 256x256, 512x512
Task attachment	10MB	Store original + compressed
Voice recording	10MB	Compress to 64kbps
Document	20MB	Store original

13. Infrastructure & DevOps

13.1 Environment Architecture

Environment	Purpose	Access
Development	Local development	Developers
Staging	Pre-production testing	Team
Production	Live users	Public

13.2 Deployment Pipeline

Code Push → GitHub Actions
                │
                ├── Lint & Type Check
                ├── Unit Tests
                ├── Integration Tests
                │
                ▼
            Build
                │
                ├── Docker Image
                ├── Static Assets
                │
                ▼
        ┌───────┴───────┐
        │               │
    Staging         Production
    (auto)          (manual approval)

13.3 Infrastructure Components

Component	Provider	Configuration
Web Hosting	Vercel	Pro plan, auto-scaling
Database	Supabase	Pro plan, daily backups
Cache	Upstash Redis	Pro plan, 256MB
File Storage	Supabase Storage	Standard tier
CDN	Vercel Edge Network	Included
DNS	Cloudflare	Pro plan
Email	Resend	Pro plan
SMS	MSG91	Enterprise
Push	Firebase	Spark (free)

13.4 Scaling Strategy

Horizontal Scaling:

Serverless functions auto-scale with Vercel
Database read replicas for read-heavy workloads
Redis cluster for cache scaling

Vertical Scaling:

Database: Upgrade Supabase tier as needed
Increase function memory for compute-heavy tasks

13.5 Disaster Recovery

Aspect	Strategy	RTO	RPO
Database	Point-in-time recovery	1 hour	5 minutes
File storage	Cross-region replication	1 hour	1 hour
Application	Multi-region deployment	Minutes	N/A
Configuration	Version controlled	Minutes	N/A

13.6 Backup Schedule

Data Type	Frequency	Retention
Database (full)	Daily	30 days
Database (incremental)	Hourly	7 days
File storage	Daily	30 days
Logs	Real-time	30 days
Analytics	Daily	1 year

14. Testing Strategy

14.1 Testing Pyramid

            ┌───────────┐
            │   E2E     │  ← 5% of tests
            │   Tests   │
            ├───────────┤
            │Integration│  ← 25% of tests
            │   Tests   │
            ├───────────┤
            │   Unit    │  ← 70% of tests
            │   Tests   │
            └───────────┘

14.2 Test Types

Type	Framework	Coverage Target
Unit	Vitest	80% line coverage
Integration	Vitest + Supertest	Critical paths
E2E	Playwright	Happy paths + edge cases
Visual Regression	Percy/Chromatic	UI components
Performance	k6	Load testing
Security	OWASP ZAP	Security scanning

14.3 Test Data Strategy

Test Fixtures:

Seed data scripts for each environment
Factory functions for dynamic data generation
Anonymized production data samples for edge cases

Test Isolation:

Each test creates its own data
Database transactions with rollback
Unique identifiers to prevent collisions

14.4 CI/CD Test Requirements

Stage	Tests	Blocking
Pre-commit	Lint, Type check	Yes
Pull Request	Unit, Integration	Yes
Staging Deploy	E2E, Visual	Yes
Production Deploy	Smoke tests	Yes
Nightly	Full E2E, Performance	Alert only

15. Monitoring & Observability

15.1 Metrics to Track

Application Metrics:

Metric	Type	Alert Threshold
Request rate	Counter	N/A (baseline)
Error rate	Percentage	> 1%
Response time P95	Histogram	> 500ms
Active users	Gauge	N/A
WebSocket connections	Gauge	> 90% capacity

Business Metrics:

Metric	Type	Dashboard
New signups	Counter	Daily
Active households	Gauge	Daily
Tasks created	Counter	Daily
Conversion rate	Percentage	Weekly
Churn indicators	Composite	Weekly

15.2 Logging Strategy

Log Levels:

Level	Use Case
ERROR	Unexpected errors, exceptions
WARN	Degraded functionality, retries
INFO	Request/response, business events
DEBUG	Detailed debugging (dev only)

Structured Logging Format:

{
  "timestamp": "2026-01-20T10:30:00Z",
  "level": "INFO",
  "message": "Task created",
  "request_id": "req_abc123",
  "user_id": "user_xyz",
  "household_id": "hh_789",
  "task_id": "task_456",
  "duration_ms": 45
}

15.3 Alerting Rules

Alert	Condition	Severity	Channel
High error rate	> 1% for 5 min	Critical	PagerDuty, Slack
Slow responses	P95 > 1s for 5 min	Warning	Slack
Database connectivity	Connection failures	Critical	PagerDuty
External API failure	3 consecutive failures	Warning	Slack
Payment failure spike	> 10% failure rate	Critical	PagerDuty, Email
Memory usage high	> 80%	Warning	Slack

15.4 Tracing

Distributed Tracing:

Implement OpenTelemetry for request tracing
Trace ID propagated across all services
Capture traces for slow requests (> 500ms)
Sample rate: 10% of requests (adjust based on volume)

16. Mobile-Specific Requirements

16.1 Platform Requirements

Platform	Minimum Version	Target
iOS	14.0	Latest - 2
Android	API 26 (8.0)	Latest - 2

16.2 Mobile-Specific Features

Feature	iOS	Android
Push Notifications	APNs	FCM
Voice Input	SFSpeechRecognizer	SpeechRecognizer
Biometric Auth	Face ID / Touch ID	Fingerprint / Face
Background Sync	BGTaskScheduler	WorkManager
Deep Linking	Universal Links	App Links
Widgets	WidgetKit	App Widgets
Siri Integration	SiriKit	N/A
Google Assistant	N/A	Actions on Google

16.3 App Store Requirements

iOS App Store:

Privacy labels configured
App tracking transparency implemented
No private API usage
Accessibility compliance

Google Play Store:

Data safety section completed
Target API level compliance
64-bit support
No deprecated permission usage

16.4 Mobile Performance Targets

Metric	Target
Cold start time	< 2 seconds
Time to interactive	< 3 seconds
Frame rate	60 fps
Memory usage	< 200MB
Battery impact	Minimal (no constant polling)
Offline capability	Core features work offline

17. Offline Support & Sync

17.1 Offline Capabilities

Feature	Offline Support	Sync Strategy
View tasks	Full	Background sync
Create task	Queue for sync	On reconnect
Complete task	Queue for sync	On reconnect
View calendar	Cached data	Background sync
View grocery list	Full	Real-time when online
Check grocery item	Queue for sync	On reconnect
Voice capture	Queue recording	On reconnect

17.2 Local Storage Schema

SQLite Tables (Mobile):

tasks
events
grocery_lists
grocery_items
sync_queue
user_preferences
cached_briefings

17.3 Sync Conflict Resolution

Conflict Type	Resolution
Same field edited	Last-write-wins with server timestamp
Task completed by both	First completion wins
Task deleted by one, edited by other	Deletion wins
Concurrent grocery item checks	Merge (both checked)

17.4 Sync Protocol

Client Reconnects → Fetch sync timestamp
                          │
                          ▼
              Pull changes since last sync
                          │
                          ▼
              Apply server changes locally
                          │
                          ▼
              Push queued local changes
                          │
                          ▼
              Resolve conflicts
                          │
                          ▼
              Update sync timestamp

18. Internationalization

18.1 Supported Languages

Language	Code	Status	Coverage
English	en	Primary	100%
Hindi	hi	Phase 2	80%
Tamil	ta	Phase 3	Planned
Telugu	te	Phase 3	Planned
Kannada	kn	Phase 3	Planned

18.2 i18n Implementation

String Management:

Use i18next for React/React Native
Store translations in JSON files
Support for pluralization
Support for interpolation

Date/Time Localization:

Use date-fns for date formatting
Respect user timezone (stored in profile)
Default timezone: Asia/Kolkata
Support for 12/24 hour format preference

Number/Currency Formatting:

Indian numbering system (lakhs, crores)
INR currency formatting
Support for international formats (for future expansion)

18.3 RTL Support

Not required for initial launch (Indian languages are LTR)
Architecture should not preclude future RTL support

19. Accessibility Requirements

19.1 WCAG Compliance

Target: WCAG 2.1 Level AA

Criterion	Requirement
Color contrast	Minimum 4.5:1 for normal text
Focus indicators	Visible focus states
Keyboard navigation	All features accessible via keyboard
Screen reader	Semantic HTML, ARIA labels
Text scaling	Support up to 200% zoom
Motion	Respect reduced motion preference

19.2 Mobile Accessibility

Platform	Features
iOS	VoiceOver support, Dynamic Type, Bold Text
Android	TalkBack support, Font scaling, High contrast

19.3 Accessible Components

Component	Accessibility Requirement
Buttons	Descriptive labels, touch target 44x44px
Forms	Associated labels, error descriptions
Modals	Focus trap, escape to close
Lists	Proper list semantics
Images	Alt text for meaningful images
Icons	aria-label for interactive icons
Animations	Pause on reduced motion preference

20. Data Privacy & Compliance

20.1 Applicable Regulations

Regulation	Applicability
IT Act 2000 (India)	Primary - Indian operations
DPDP Act 2023 (India)	Primary - Personal data protection
GDPR	If serving EU users (future)
CCPA	If serving California users (future)

20.2 Data Classification

Classification	Examples	Handling
Public	App name, features	No restrictions
Internal	Aggregate analytics	Internal use only
Confidential	User emails, names	Encrypted, access-controlled
Sensitive	Phone numbers, addresses	Encrypted, minimal access
Restricted	Passwords, payment data	Highest security

20.3 User Rights Implementation

Right	Implementation
Right to access	Data export feature (JSON/CSV)
Right to correction	Edit profile, edit content
Right to deletion	Account deletion with 30-day grace
Right to portability	Export data in standard formats
Right to object	Opt-out of marketing, analytics
Consent management	Granular consent settings

20.4 Data Retention Policy

Data Type	Retention Period	After Deletion
User account	Until deletion requested	30 days grace, then purge
Tasks	Until household deleted	Anonymize for analytics
Activity logs	12 months	Archive, then delete
Analytics	Aggregated indefinitely	Anonymized
Backups	30 days	Auto-purge
Audit logs	7 years	Secure archive

20.5 Privacy by Design Principles

Data Minimization: Collect only necessary data
Purpose Limitation: Use data only for stated purposes
Consent: Explicit consent for data collection
Transparency: Clear privacy policy, in-app disclosures
Security: Encryption, access controls, security testing
Accountability: Data protection officer, audit trails

Appendix A: API Error Codes

Code	HTTP Status	Description
`VALIDATION_ERROR`	400	Invalid request data
`AUTHENTICATION_REQUIRED`	401	No valid authentication
`INVALID_TOKEN`	401	Token expired or invalid
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource not found
`CONFLICT`	409	Resource conflict
`RATE_LIMITED`	429	Too many requests
`INTERNAL_ERROR`	500	Server error
`SERVICE_UNAVAILABLE`	503	Service temporarily unavailable

Appendix B: Environment Variables

Variable	Description	Required
`DATABASE_URL`	PostgreSQL connection string	Yes
`REDIS_URL`	Redis connection string	Yes
`JWT_SECRET`	JWT signing secret	Yes
`OPENAI_API_KEY`	OpenAI API key	Yes
`GOOGLE_CLIENT_ID`	Google OAuth client ID	Yes
`GOOGLE_CLIENT_SECRET`	Google OAuth client secret	Yes
`RAZORPAY_KEY_ID`	Razorpay API key	Yes
`RAZORPAY_KEY_SECRET`	Razorpay secret	Yes
`RESEND_API_KEY`	Resend email API key	Yes
`MSG91_AUTH_KEY`	MSG91 SMS API key	Yes
`FCM_SERVER_KEY`	Firebase Cloud Messaging key	Yes
`SENTRY_DSN`	Sentry error tracking DSN	Yes
`NEXT_PUBLIC_APP_URL`	Public app URL	Yes

Appendix C: Glossary

Term	Definition
Household	A group of users managing shared home operations
Mental Load	The cognitive labor of managing household tasks
Briefing	AI-generated summary of tasks and events
Power Hour	Focused task completion session
Load Balance	Distribution of tasks between household members
Capture	The act of adding a task via voice, text, or email

Document Version: 1.0 Last Updated: January 2026 Classification: Internal - Engineering Team Owner: Engineering Lead

FilesExpand file tree

technical-specification.md

Latest commit

History