# LifeOS - AI-Powered Life Management System

<div align="center">

![LifeOS Logo](docs/assets/logo.png)

**Your AI-powered personal assistant for tasks, calendar, and projects**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
[![Next.js](https://img.shields.io/badge/Next.js-14-black.svg)](https://nextjs.org/)
[![Prisma](https://img.shields.io/badge/Prisma-5.8-2D3748.svg)](https://www.prisma.io/)

[Demo](#demo) • [Features](#features) • [Quick Start](#quick-start) • [Documentation](#documentation) • [Architecture](#architecture)

</div>

---

## Overview

LifeOS is a complete AI-powered life management system built for the **Amazon Alexa+ Hackathon**. It demonstrates the full potential of the Model Context Protocol (MCP) for autonomous agent orchestration.

**Key Highlights:**
- 🤖 **12 MCP Tools** - Custom server for task, calendar, and project management
- 🔄 **Real-Time Agent Streaming** - Watch AI think and act in real-time via SSE
- 🎯 **Smart Planning** - Multi-provider AI (OpenAI/Anthropic) with rule-based fallback
- 🗣️ **Voice-Ready** - Alexa simulator demonstrates conversational interface
- 🏗️ **Production-Ready** - TypeScript monorepo with PostgreSQL, tested and documented

---

## Demo

### Live Demo User: Alex Chen

LifeOS includes a fully seeded demo persona to showcase realistic workflows:

**Profile:**
- Product Manager at a tech startup
- Managing 3 active projects (product launch, hiring, Q1 planning)
- 8 pending tasks across different priorities
- Busy calendar with 8 events this week

### Try These Commands

Open the Alexa simulator at http://localhost:3000/alexa and try:

```
"What should I focus on today?"
→ Agent analyzes tasks + calendar and provides prioritized recommendations

"Schedule a design review meeting for next Tuesday at 2pm"
→ Agent finds availability, books meeting, and confirms

"Create a high priority task to finalize pricing strategy, due Friday"
→ Agent creates task, links to relevant project, and confirms

"Help me prepare for the product launch next week"
→ Agent generates multi-step action plan with concrete next steps
```

### Visual Tour

**Dashboard:**
![Dashboard Screenshot](docs/assets/dashboard.png)
*Integrated view of tasks, calendar, projects, and live agent activity*

**Alexa Simulator:**
![Alexa Simulator Screenshot](docs/assets/alexa-simulator.png)
*Voice-first conversational interface with real-time streaming*

**Agent Activity Panel:**
![Agent Panel Screenshot](docs/assets/agent-panel.png)
*Transparent view into AI decision-making and tool execution*

---

## Features

### 🎯 Intelligent Task Management

- **Natural Language Input** - "Create a task to review design docs by Friday"
- **Smart Prioritization** - AI recommends what to work on based on deadlines and calendar
- **Project Linking** - Automatic categorization into relevant projects
- **Status Tracking** - Todo, In Progress, Completed, Cancelled

### 📅 Contextual Calendar

- **Time-Block Visualization** - See available gaps for task scheduling
- **Smart Scheduling** - "Find time for a 1-hour meeting next week"
- **Conflict Detection** - Agent avoids double-booking
- **Event Management** - Create, move, and delete events via natural language

### 🤖 Autonomous Agent

- **Multi-Tool Orchestration** - Chains multiple MCP tools to achieve goals
- **Transparent Decision-Making** - Real-time streaming of thoughts and actions
- **Error Recovery** - Handles failures gracefully with retry logic
- **Context Awareness** - Remembers conversation history and learns patterns

### 🗣️ Voice-First Design

- **Alexa Simulator** - Test conversational flows before Alexa integration
- **Natural Responses** - Conversational language optimized for voice
- **Multi-Turn Dialogs** - Agent maintains context across exchanges
- **Proactive Suggestions** - "You have 3 tasks due tomorrow. Want me to reschedule?"

### 🔧 Developer Experience

- **TypeScript Monorepo** - Shared types, schemas, and utilities via pnpm workspaces
- **Type-Safe API** - Zod validation from database to frontend
- **Hot Reload** - Instant updates during development
- **Comprehensive Testing** - 65+ unit tests, integration tests ready

---

## Quick Start

### Prerequisites

Ensure you have these installed:
- **Node.js** 18+ ([download](https://nodejs.org/))
- **Docker Desktop** ([download](https://www.docker.com/products/docker-desktop))
- **pnpm** 8+ (install: `npm install -g pnpm`)

### Installation (5 minutes)

1. **Clone and Install Dependencies**

```bash
cd "c:\Users\admin\Desktop\Amazon Developer"
pnpm install
```

2. **Start PostgreSQL Database**

```bash
docker compose up -d
```

Verify database is running:
```bash
docker compose ps
# Should show lifeos-db as "running"
```

3. **Run Database Migrations**

```bash
pnpm --filter @lifeos/database db:migrate
```

This creates all tables (User, Project, Task, CalendarEvent, AgentSession, ActionLog).

4. **Seed Demo Data**

```bash
pnpm --filter @lifeos/database db:seed
```

This creates Alex Chen demo user with 3 projects, 8 tasks, and 8 calendar events.

5. **Start Development Servers**

Open **two terminal windows**:

```bash
# Terminal 1: Start MCP Server (port 3001)
pnpm --filter @lifeos/mcp-server dev

# Terminal 2: Start Web App (port 3000)
pnpm --filter @lifeos/web dev
```

6. **Access the Application**

- **Landing Page:** http://localhost:3000
- **Dashboard:** http://localhost:3000/dashboard
- **Alexa Simulator:** http://localhost:3000/alexa

### Verify Installation

Check that both servers are healthy:

```bash
# MCP Server health
curl http://localhost:3001/health
# Expected: {"status":"ok","toolsRegistered":12}

# Web App health
curl http://localhost:3000/api/health
# Expected: {"status":"ok"}
```

---

## Configuration

### Environment Variables

The project uses `.env.local` for configuration. Default values are provided for quick start, but you can customize:

```bash
# Database
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/lifeos

# MCP Server
MCP_SECRET=dev-secret-replace-with-32-char-minimum-for-production-use
MCP_SERVER_URL=http://localhost:3001

# AI Provider (optional - uses rule-based fallback if not set)
AI_PROVIDER=openai              # or "anthropic"
AI_MODEL=gpt-4o                 # or "claude-3-5-sonnet-20241022"
AI_API_KEY=                     # Add your API key here for LLM-powered planning

# Demo Mode
DEMO_MODE=true                  # Set to false for production
DEMO_USER_ID=00000000-0000-0000-0000-000000000001

# NextAuth (for production authentication)
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=dev-nextauth-secret-change-for-production
```

### Adding AI Provider

For better agent responses, add your AI provider API key:

**OpenAI:**
```bash
AI_PROVIDER=openai
AI_MODEL=gpt-4o
AI_API_KEY=sk-proj-...
```

**Anthropic:**
```bash
AI_PROVIDER=anthropic
AI_MODEL=claude-3-5-sonnet-20241022
AI_API_KEY=sk-ant-...
```

Then restart both servers to apply changes.

---

## Architecture

LifeOS is built as a **TypeScript monorepo** using pnpm workspaces:

```
lifeos/
├── packages/
│   ├── shared/         # Shared schemas, types, error classes
│   ├── database/       # Prisma schema, migrations, seed
│   ├── ai/             # AI provider abstraction, agent orchestrator
│   └── ui/             # Design tokens and shared UI utilities
│
├── apps/
│   ├── mcp-server/     # Express MCP server with 12 tools
│   └── web/            # Next.js 14 web application
│
├── docs/               # Documentation and compliance
├── .env.local          # Environment configuration
├── docker-compose.yml  # PostgreSQL container
└── pnpm-workspace.yaml # Monorepo configuration
```

### Technology Stack

**Backend:**
- **MCP Server:** Express.js with Streamable HTTP transport
- **Database:** PostgreSQL 16 with Prisma ORM
- **AI:** OpenAI GPT-4o / Anthropic Claude with abstraction layer
- **Validation:** Zod schemas for type-safe APIs
- **Logging:** Winston with structured JSON logs

**Frontend:**
- **Framework:** Next.js 14 with App Router
- **UI:** React 18, TailwindCSS 3
- **State:** Zustand with persistence
- **Real-Time:** Server-Sent Events (SSE) for agent streaming
- **Icons:** Lucide React

**Development:**
- **Language:** TypeScript 5.3
- **Package Manager:** pnpm 8
- **Testing:** Vitest (unit), Playwright (e2e, planned)
- **Linting:** ESLint + Prettier
- **Version Control:** Git

### Data Flow

```
User Input (Natural Language)
    ↓
Next.js Web App (/alexa or /dashboard)
    ↓
API Route (/api/mcp) with SSE streaming
    ↓
MCP Server (Express on port 3001)
    ↓
Agent Orchestrator (AI planning + tool selection)
    ↓
MCP Tools (12 tools for CRUD operations)
    ↓
PostgreSQL Database (Prisma ORM)
    ↓
Response (Natural Language + Structured Data)
    ↓
Real-Time UI Update (SSE stream + Zustand state)
```

### MCP Tools

The system includes 12 production-ready MCP tools:

| Tool | Description | Parameters |
|------|-------------|-----------|
| `get_tasks` | Fetch user's tasks with filters | userId, status, priority, projectId |
| `create_task` | Create a new task | userId, title, description, priority, dueDate |
| `update_task` | Update existing task | taskId, updates (status, priority, etc.) |
| `delete_task` | Delete a task | taskId |
| `get_schedule` | Fetch calendar events | userId, startDate, endDate |
| `create_event` | Create calendar event | userId, title, startTime, endTime |
| `move_event` | Reschedule an event | eventId, newStartTime, newEndTime |
| `get_projects` | Fetch user's projects | userId, status |
| `search_context` | Cross-entity search | userId, query |
| `analyze_day` | Generate daily insights | userId, date |
| `generate_plan` | AI-powered action plan | userId, goal |
| `execute_plan` | Execute multi-step plan | userId, planId |

---

## Documentation

Comprehensive documentation is available in the `docs/` directory:

- **[HACKATHON_COMPLIANCE.md](docs/HACKATHON_COMPLIANCE.md)** - Full compliance proof for Amazon Alexa+ Hackathon
- **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** - Detailed system design and technical decisions
- **[API_REFERENCE.md](docs/API_REFERENCE.md)** - Complete API documentation for MCP tools and web endpoints
- **[DEPLOYMENT.md](docs/DEPLOYMENT.md)** - Production deployment guide (AWS, Vercel, Docker)
- **[DEVELOPMENT.md](docs/DEVELOPMENT.md)** - Development guidelines and contribution guide
- **[ALEXA_INTEGRATION.md](docs/ALEXA_INTEGRATION.md)** - Step-by-step guide to integrate with Alexa

---

## Development

### Project Structure

```
packages/shared/
├── src/
│   ├── schemas/      # Zod validation schemas
│   ├── types/        # TypeScript type definitions
│   └── errors/       # Custom error classes
└── __tests__/        # Schema validation tests

packages/database/
├── prisma/
│   ├── schema.prisma # Database schema
│   ├── migrations/   # SQL migrations
│   └── seed.ts       # Demo data seed script
└── src/
    └── client.ts     # Prisma client singleton

packages/ai/
├── src/
│   ├── providers/    # OpenAI and Anthropic adapters
│   ├── orchestrator/ # Agent loop and planning
│   └── mcp/          # MCP client wrapper
└── __tests__/        # Orchestrator tests

apps/mcp-server/
├── src/
│   ├── tools/        # 12 MCP tool implementations
│   ├── middleware/   # Auth, logging, error handling
│   └── server.ts     # Express app and MCP endpoint
└── __tests__/        # Server integration tests (planned)

apps/web/
├── src/
│   ├── app/          # Next.js App Router pages
│   ├── components/   # React components
│   ├── hooks/        # Custom React hooks
│   ├── stores/       # Zustand state stores
│   └── lib/          # Utilities and helpers
└── e2e/              # Playwright tests (planned)
```

### Common Commands

```bash
# Install dependencies
pnpm install

# Type checking
pnpm typecheck

# Linting
pnpm lint
pnpm lint:fix

# Testing
pnpm test                                   # All tests
pnpm --filter @lifeos/shared test          # Schema tests only
pnpm --filter @lifeos/ai test              # Orchestrator tests only

# Database operations
pnpm --filter @lifeos/database db:migrate  # Run migrations
pnpm --filter @lifeos/database db:seed     # Seed demo data
pnpm --filter @lifeos/database db:reset    # Reset database (WARNING: deletes data)
pnpm --filter @lifeos/database db:studio   # Open Prisma Studio UI

# Development servers
pnpm --filter @lifeos/mcp-server dev       # Start MCP server
pnpm --filter @lifeos/web dev              # Start web app

# Production build
pnpm build                                  # Build all packages and apps
```

### Adding a New MCP Tool

1. Create tool file in `apps/mcp-server/src/tools/`:

```typescript
// apps/mcp-server/src/tools/myNewTool.ts
import { z } from 'zod';
import { prisma } from '@lifeos/database';

export const myNewTool = {
  name: 'my_new_tool',
  description: 'Description of what the tool does',
  parameters: z.object({
    userId: z.string().uuid(),
    // Add your parameters here
  }),
  handler: async (params: z.infer<typeof myNewTool.parameters>) => {
    try {
      // Your implementation here
      const result = await prisma.someModel.findMany({
        where: { userId: params.userId }
      });
      
      return {
        success: true,
        data: result
      };
    } catch (error) {
      return {
        success: false,
        error: {
          code: 'MY_TOOL_ERROR',
          message: error.message
        }
      };
    }
  }
};
```

2. Register tool in `apps/mcp-server/src/tools/index.ts`:

```typescript
import { myNewTool } from './myNewTool';

export const tools: MCPTool[] = [
  // ... existing tools
  myNewTool
];
```

3. Add tests in `apps/mcp-server/__tests__/tools/myNewTool.test.ts`

4. Restart MCP server and verify:
```bash
curl http://localhost:3001/health
# Should show toolsRegistered: 13
```

### Database Schema Changes

1. Edit `packages/database/prisma/schema.prisma`
2. Create migration: `pnpm --filter @lifeos/database db:migrate --name my_change`
3. Update seed script if needed: `packages/database/prisma/seed.ts`
4. Regenerate Prisma Client: `pnpm --filter @lifeos/database build`

---

## Testing

### Current Test Coverage

- **Schema Validation:** 51 tests (100% coverage of Zod schemas)
- **Agent Orchestrator:** 14 tests (core planning and execution logic)
- **Total:** 65 unit tests

Run tests:
```bash
pnpm test
```

### Planned Tests

**Integration Tests:**
- MCP server API endpoints
- Database operations with test database
- Error handling and edge cases

**End-to-End Tests (Playwright):**
- User flows: landing → dashboard → create task
- Natural language agent interactions
- Calendar event creation and rescheduling
- Demo reset functionality

---

## Deployment

### Quick Deploy (Vercel + Railway)

**1. Deploy Web App to Vercel:**
```bash
# Install Vercel CLI
npm install -g vercel

# Deploy
cd apps/web
vercel --prod
```

**2. Deploy Database to Railway:**
1. Visit [railway.app](https://railway.app)
2. Create new project → PostgreSQL
3. Copy `DATABASE_URL` from Railway dashboard
4. Add to Vercel environment variables

**3. Deploy MCP Server to Railway:**
```bash
# Create railway.json in apps/mcp-server/
{
  "build": {
    "builder": "NIXPACKS"
  },
  "deploy": {
    "startCommand": "node dist/index.js",
    "restartPolicyType": "ON_FAILURE"
  }
}

# Deploy via Railway CLI or GitHub integration
```

**4. Configure Environment Variables:**
- Add all `.env.local` variables to Vercel and Railway
- Update `MCP_SERVER_URL` in Vercel to point to Railway MCP server
- Set `DEMO_MODE=false` for production

### Full Production Deployment

See **[docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)** for comprehensive guides:
- AWS ECS/Fargate deployment
- Docker multi-stage builds
- CI/CD with GitHub Actions
- Database backup strategies
- Monitoring and observability setup

---

## Troubleshooting

### Database Connection Issues

**Problem:** `Error: P1001: Can't reach database server`

**Solution:**
```bash
# Check if PostgreSQL container is running
docker compose ps

# If not running, start it
docker compose up -d

# Verify connection
docker compose exec db psql -U postgres -d lifeos -c "SELECT 1;"
```

---

### MCP Server Not Starting

**Problem:** `Error: Cannot find module '@lifeos/database'`

**Solution:**
```bash
# Rebuild all packages
pnpm install --force
pnpm build
```

---

### Web App Shows "Failed to Fetch"

**Problem:** Agent queries fail with network error

**Solution:**
1. Verify MCP server is running: `curl http://localhost:3001/health`
2. Check `MCP_SERVER_URL` in `.env.local` matches server address
3. Ensure `MCP_SECRET` matches between web app and MCP server
4. Check browser console for detailed error messages

---

### Agent Responses Are Generic

**Problem:** Agent gives basic responses instead of intelligent suggestions

**Solution:**
You're in demo mode using rule-based planning. For AI-powered responses:

1. Get an API key from [OpenAI](https://platform.openai.com) or [Anthropic](https://console.anthropic.com)
2. Add to `.env.local`:
   ```bash
   AI_PROVIDER=openai
   AI_API_KEY=sk-proj-...
   ```
3. Restart both servers
4. Test with same queries - responses should be more contextual

---

### Port Already in Use

**Problem:** `Error: listen EADDRINUSE: address already in use :::3000`

**Solution:**
```powershell
# Find process using port 3000
netstat -ano | findstr :3000

# Kill the process (replace PID with actual process ID)
taskkill /PID <PID> /F

# Or use a different port
PORT=3002 pnpm --filter @lifeos/web dev
```

---

## Contributing

LifeOS was built for the Amazon Alexa+ Hackathon as a solo project, but contributions are welcome!

### Development Setup

1. Fork the repository
2. Clone your fork: `git clone https://github.com/yourusername/lifeos.git`
3. Create a branch: `git checkout -b feature/my-feature`
4. Make changes and test thoroughly
5. Run linting and tests: `pnpm lint && pnpm test`
6. Commit with clear messages: `git commit -m "feat: add new feature"`
7. Push and create PR: `git push origin feature/my-feature`

### Code Style

- Use TypeScript for all new code
- Follow existing patterns and conventions
- Add Zod schemas for new data types
- Write tests for new features
- Update documentation as needed

### Commit Convention

Follow [Conventional Commits](https://www.conventionalcommits.org/):
- `feat:` - New feature
- `fix:` - Bug fix
- `docs:` - Documentation changes
- `refactor:` - Code refactoring
- `test:` - Adding tests
- `chore:` - Maintenance tasks

---

## Roadmap

### v1.1 (Next 1-2 months)
- [ ] Mobile app (React Native)
- [ ] Advanced AI learning from user patterns
- [ ] Google Calendar integration
- [ ] Slack notifications
- [ ] Email parsing for task creation

### v1.2 (3-6 months)
- [ ] Official Alexa Skill launch
- [ ] Team workspaces and collaboration
- [ ] Admin dashboard
- [ ] Analytics and productivity insights
- [ ] SSO (SAML/OIDC)

### v2.0 (6-12 months)
- [ ] Fine-tuned AI model on user data
- [ ] Public API for third-party integrations
- [ ] Plugin system
- [ ] White-label solution
- [ ] Real-time collaborative planning

---

## License

This project is licensed under the **MIT License**. See [LICENSE](LICENSE) file for details.

```
MIT License

Copyright (c) 2026 LifeOS

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

---

## Support

### Questions or Issues?

1. Check the [Documentation](docs/)
2. Review [Troubleshooting](#troubleshooting) section
3. Search [existing issues](https://github.com/lifeos/lifeos/issues)
4. Create a [new issue](https://github.com/lifeos/lifeos/issues/new) with:
   - Clear description of the problem
   - Steps to reproduce
   - Expected vs actual behavior
   - System information (OS, Node version, etc.)

### Hackathon Judges

For hackathon evaluation:
- All setup instructions are in [Quick Start](#quick-start)
- Demo walkthrough is in [Demo](#demo) section
- Full compliance proof is in [docs/HACKATHON_COMPLIANCE.md](docs/HACKATHON_COMPLIANCE.md)
- Technical deep dive is in [Architecture](#architecture) section

---

## Acknowledgments

Built with:
- [Next.js](https://nextjs.org/) - React framework
- [Prisma](https://www.prisma.io/) - Database ORM
- [OpenAI](https://openai.com/) - GPT-4o API
- [Anthropic](https://www.anthropic.com/) - Claude API
- [Model Context Protocol](https://modelcontextprotocol.io/) - Agent tool specification
- [TailwindCSS](https://tailwindcss.com/) - Styling
- [Zod](https://zod.dev/) - Schema validation
- [Zustand](https://zustand-demo.pmnd.rs/) - State management

Special thanks to the Amazon Alexa+ team for hosting this hackathon and inspiring innovation in voice-AI integration.

---

<div align="center">

**Built for Amazon Alexa+ Hackathon 2026**

[View Demo](http://localhost:3000) • [Read Docs](docs/) • [Report Bug](https://github.com/lifeos/lifeos/issues) • [Request Feature](https://github.com/lifeos/lifeos/issues)

Made with ❤️ by LifeOS Team

</div>