# Project Comprehensive Overview

## System Architecture

### Frontend
- **Technology Stack**: React with TypeScript
- **Routing Framework**: Advanced routing system with nested routes
- **State Management**: Custom stores using Zustand-like pattern

### Backend Integration
- WordPress as the primary backend
- Custom authentication and API layer
- Seamless integration between React frontend and WordPress

## Routing Structure

### Authentication Routes
- `/sign-in`: User login
- `/sign-up`: User registration
- `/forgot-password`: Password recovery
- `/otp`: Multi-factor authentication
- `/google-callback`: OAuth integration

### Authenticated Routes
- `/_authenticated/`:
  - `/settings/`: User account settings
    - `/account`: Account details
    - `/appearance`: UI customization
  - `/apps/`: Application management
  - `/tasks/`: Task tracking
  - `/help-center/`: Support and documentation

### Error Handling Routes
- `/401`: Unauthorized access
- `/403`: Forbidden access
- `/404`: Page not found
- `/500`: Server error
- `/503`: Service unavailable

## Key Services

### Authentication Service (`src/services/wordpress-auth.ts`)
- WordPress-specific authentication mechanisms
- Handles:
  - User authentication
  - Token management
  - User profile retrieval

#### Interfaces
- `WordPressAuthResponse`: 
  ```typescript
  {
    token: string
    user_email: string
    user_nicename: string
    user_display_name: string
    user_id: number
  }
  ```
- `WordPressUser`: Detailed user information
- `WordPressSite`: Site metadata

### API Key Management (`src/stores/apiKeyStore.ts`)
- Generate application passwords
- List and revoke API keys
- Secure access token management

#### Interfaces
- `ApiKey`:
  ```typescript
  {
    uuid: string
    name: string
    created: number
    last_used?: number
  }
  ```

### Credit Service (`src/services/credit-service.ts`)
- Manages user credits and transactions
- Tracks subscription plans
- Handles billing cycles

#### Interfaces
- `CreditBalance`:
  ```typescript
  {
    balance: number
    formatted_balance: string
    transactions: Array<{
      type: 'credit' | 'debit'
      amount: number
      balance: number
      date: string
      description: string
    }>
    subscriptionPlan: string
    monthlyAllocation: number
    monthlyUsage: number
  }
  ```

## Authentication Flow

1. User initiates login/signup
2. Frontend communicates with WordPress authentication endpoint
3. WordPress validates credentials
4. Returns authentication token
5. Frontend stores token and user information
6. Subsequent API calls include authentication token

## WordPress Plugin Interactions

### Authentication
- Uses WordPress's built-in REST API
- Generates application-specific passwords
- Supports multiple authentication methods:
  - Standard username/password
  - Google OAuth
  - Multi-factor authentication

### API Integration
- Custom WordPress plugin provides extended API endpoints
- Manages:
  - User profiles
  - Site information
  - Billing and credit systems
  - API key management

## Security Considerations
- Token-based authentication
- Secure storage of access tokens
- Role-based access control
- OAuth integration
- Multi-factor authentication support

## Frontend State Management Patterns

### Auth Store (`src/stores/authStore.ts`)
- Centralized authentication state
- Methods for:
  - User authentication
  - Token validation
  - Logout
  - User information management

#### Auth State Structure
```typescript
interface AuthState {
  user: AuthUser | null
  accessToken: string
  isAuthenticated(): boolean
  login(email: string, password: string): Promise<boolean>
  logout(): void
}
```

## Deployment and Scaling
- Serverless-compatible architecture
- Decoupled frontend and backend
- Supports multiple WordPress instances
- Scalable authentication mechanism


---

**Note**: This is a comprehensive overview of the project's architecture, integrating React frontend with WordPress backend, focusing on authentication, API management, and state handling.