# Phase 1: Foundation - Context Bundle

## Task Description

Implement Phase 1 Foundation for MoreMinimore SAAS platform. This phase establishes the core infrastructure including project setup, database configuration, authentication system, user management, and CI/CD pipeline.

## Scope Boundaries

### In Scope

- Next.js 15 project initialization with TypeScript
- PostgreSQL database setup with Drizzle ORM
- Complete database schema (20+ tables from SPECIFICATION.md)
- Redis caching setup
- JWT-based authentication system
- User management APIs and UI
- CI/CD pipeline with GitHub Actions
- Automated testing setup (Vitest, Playwright)

### Out of Scope

- Organization management (Phase 2)
- Project management (Phase 2)
- AI integration (Phase 2)
- Easypanel integration (Phase 4)
- Gitea integration (Phase 5)
- Billing system (Phase 6)

## Technical Requirements

### Technology Stack

- **Frontend**: Next.js 15 (App Router), React 19, Tailwind CSS 4, shadcn/ui
- **Backend**: Next.js API Routes, Node.js 20+
- **Database**: PostgreSQL 16+, Drizzle ORM
- **Cache**: Redis 7+
- **State**: Zustand (global), React Query (server state)
- **Testing**: Vitest (unit), Playwright (E2E)
- **CI/CD**: GitHub Actions

### Database Schema

All tables from SPECIFICATION.md lines 141-397:

- users, organizations, organization_members
- projects, project_versions
- chats, messages, prompts
- ai_providers, ai_models, user_api_keys
- design_systems, deployment_logs
- invoices, subscription_events
- audit_logs, sessions
- email_verification_tokens, password_reset_tokens

### Authentication Requirements

- JWT access tokens (15 min expiration)
- JWT refresh tokens (7 days expiration)
- HTTP-only cookies for token storage
- Email verification required
- Password reset flow
- Role-based authorization (admin, co_admin, owner, user)

## Constraints

### Code Quality Standards

- Pure functions (no side effects)
- Immutability (create new data, don't modify)
- Small functions (< 50 lines)
- Explicit dependencies (dependency injection)
- Modular design (< 100 lines per component)

### Testing Requirements

- AAA pattern (Arrange → Act → Assert)
- Critical code: 100% coverage
- High priority: 90%+ coverage
- Medium priority: 80%+ coverage

### Security Requirements

- Never expose sensitive data in logs
- Use environment variables for secrets
- Validate all input data
- Use parameterized queries
- Implement rate limiting
- CSRF protection

## Expected Deliverables

### 1. Project Structure

```
src/
├── app/                    # Next.js App Router
│   ├── api/               # API routes
│   ├── auth/              # Auth pages
│   ├── dashboard/         # Dashboard pages
│   └── layout.tsx
├── components/            # React components
│   ├── ui/               # shadcn/ui components
│   ├── auth/             # Auth components
│   └── dashboard/        # Dashboard components
├── lib/                  # Utilities
│   ├── db/              # Database utilities
│   ├── auth/            # Auth utilities
│   └── utils.ts
├── services/            # Business logic
│   ├── auth.service.ts
│   ├── user.service.ts
│   └── email.service.ts
├── types/               # TypeScript types
│   └── index.ts
└── middleware.ts        # Next.js middleware
```

### 2. Database

- PostgreSQL database `moreminimore`
- Drizzle ORM configured
- All tables created with proper indexes
- Initial migration generated and applied
- Redis connection configured

### 3. Authentication

- Password hashing utility (bcrypt)
- JWT generation/verification utilities
- Auth APIs: register, login, refresh, logout, verify-email, forgot-password, reset-password
- Auth middleware: requireAuth, requireRole, requireOrgMembership
- Session management in database

### 4. User Management

- User profile APIs (GET/PATCH /api/users/me)
- Admin user management APIs (GET/PATCH/DELETE /api/users)
- User profile page
- Settings page
- Admin user management page

### 5. CI/CD

- GitHub Actions workflow file
- Automated testing on push/PR
- Test coverage reporting
- Build validation

## Acceptance Criteria

### Project Setup

- [ ] Next.js 15 project created with TypeScript
- [ ] Tailwind CSS 4 configured
- [ ] shadcn/ui components installed
- [ ] ESLint and Prettier configured
- [ ] Path aliases configured (@/components, @/lib, etc.)
- [ ] Environment variables template created

### Database

- [ ] PostgreSQL database created
- [ ] Drizzle ORM configured
- [ ] All 20+ tables defined in schema
- [ ] Indexes created for performance
- [ ] Initial migration generated
- [ ] Migration applied successfully
- [ ] Redis connection tested

### Authentication

- [ ] Password hashing/verification working
- [ ] JWT tokens generated with correct expiration
- [ ] Register API creates user and sends verification email
- [ ] Login API generates tokens and sets cookies
- [ ] Refresh API rotates tokens correctly
- [ ] Logout API clears cookies and invalidates session
- [ ] Email verification API works
- [ ] Password reset flow works end-to-end
- [ ] Auth middleware protects routes correctly
- [ ] Role-based authorization works

### User Management

- [ ] User profile API returns correct data
- [ ] User profile update works
- [ ] Password change works
- [ ] Admin can list all users
- [ ] Admin can update user details
- [ ] Admin can ban/unban users
- [ ] User profile page displays correctly
- [ ] Settings page works
- [ ] Admin user management page works

### CI/CD

- [ ] GitHub Actions workflow runs on push
- [ ] Tests execute automatically
- [ ] Coverage report generated
- [ ] Build validation passes
- [ ] PR checks work

## Context Files

### Code Quality Standards

- Location: /Users/kunthawatgreethong/.config/opencode/context/core/standards/code-quality.md
- Key principles: Modular, Functional, Maintainable
- Critical patterns: Pure functions, immutability, composition, dependency injection
- Anti-patterns: Mutation, side effects, deep nesting, god modules

### Documentation Standards

- Location: /Users/kunthawatgreethong/.config/opencode/context/core/standards/documentation.md
- Golden Rule: If users ask the same question twice, document it
- Document WHY decisions were made, not just WHAT code does

### Testing Standards

- Location: /Users/kunthawatgreethong/.config/opencode/context/core/standards/test-coverage.md
- Golden Rule: If you can't test it easily, refactor it
- AAA pattern: Arrange → Act → Assert
- Coverage goals: Critical 100%, High 90%+, Medium 80%+

### Essential Patterns

- Location: /Users/kunthawatgreethong/.config/opencode/context/core/essential-patterns.md
- Core patterns: Error handling, validation, security, logging, pure functions
- ALWAYS: Handle errors gracefully, validate input, use env vars for secrets
- NEVER: Expose sensitive info, hardcode credentials, skip validation

### Specification

- Location: /Users/kunthawatgreethong/Gitea/moreminimore-vibe/Websitebuilder/SPECIFICATION.md
- Complete technical specification with database schema, API design, authentication flow

### Task Breakdown

- Location: /Users/kunthawatgreethong/Gitea/moreminimore-vibe/Websitebuilder/TASKS.md
- Detailed task breakdown for all phases

## Risks & Considerations

### Technical Risks

- PostgreSQL setup complexity on local development
- Redis configuration and connection pooling
- JWT token security and rotation
- Email service integration (Resend/SendGrid)
- Database migration conflicts

### Mitigation Strategies

- Use Docker for local PostgreSQL/Redis if needed
- Implement comprehensive error handling
- Add extensive logging for debugging
- Create rollback procedures for migrations
- Test authentication flow thoroughly

## Next Steps

After Phase 1 completion:

1. Validate all acceptance criteria
2. Run full test suite
3. Document any deviations
4. Prepare for Phase 2: Core Features

---

**Session ID**: ses_phase1_foundation
**Created**: January 19, 2026
**Priority**: High
**Estimated Duration**: 4 weeks