# MaplePress Frontend

React-based web application for managing MaplePress cloud services for WordPress.

## Features

- User authentication (login/register)
- Dashboard for managing WordPress sites
- Cloud-based search indexing
- API key management
- Analytics and metrics

## Tech Stack

- **React 19** - UI framework
- **Vite** - Build tool and dev server
- **TailwindCSS 4** - Utility-first CSS
- **react-router** - Client-side routing

## Getting Started

### Prerequisites

- Node.js 18+
- npm or yarn

### Installation

```bash
# Install dependencies
npm install

# Copy environment variables
cp .env.example .env

# Edit .env and configure your backend API URL
```

### Development

```bash
# Start development server
npm run dev

# The app will be available at http://localhost:5173
```

### Building

```bash
# Build for production
npm run build

# Preview production build
npm run preview
```

### Linting

```bash
# Run ESLint
npm run lint
```

## Project Structure

```
src/
├── services/          # Service layer (business logic)
│   ├── Manager/       # Manager services
│   ├── API/          # API client
│   └── Services.jsx  # Service registry
├── pages/            # Page components
│   ├── Home/         # Landing page
│   ├── Auth/         # Login/Register
│   └── Dashboard/    # User dashboard
├── App.jsx           # Main app with routing
└── main.jsx          # Entry point
```

## Architecture

The application follows a clean architecture pattern with:

1. **Service Layer** - Business logic and API communication
2. **Pages** - UI components organized by feature
3. **Dependency Injection** - Services provided via React Context

See [FRONTEND_ARCHITECTURE.md](./docs/FRONTEND_ARCHITECTURE.md) for detailed architecture documentation.

## Current Implementation Status

✅ **Implemented:**
- Project structure and organization
- Service layer with dependency injection
- **AuthManager service** (complete with token storage and automatic refresh)
- **ApiClient** for HTTP requests (with automatic token refresh)
- **HealthService** - Backend health check and monitoring
- **RegisterService** - Full registration API integration
- **LoginService** - Full login API integration
- **RefreshTokenService** - Full token refresh API integration
- **HelloService** - Authenticated test endpoint
- **MeService** - User profile with role-based helpers
- **TenantService** - Tenant/organization management
- **UserService** - User management with tenant context
- **SiteService** - WordPress site management with API key handling
- **AdminService** - Admin account management and lockout handling
- Home/landing page
- **Login page** - Complete with backend integration
- **Register page** - Complete with all required fields
- Dashboard page (stub)
- Routing setup
- Token storage in localStorage
- Token expiry detection
- **Automatic token refresh** (proactive and reactive)
- Session persistence

🚧 **To be implemented:**
- Protected route guards
- Logout API integration
- API key management UI
- Site management UI
- Search index configuration
- Analytics dashboard
- User profile management
- Password recovery flow

## Environment Variables

Create a `.env` file based on `.env.example`:

```bash
# Backend API URL
VITE_API_BASE_URL=http://localhost:8000
```

## Available Pages

- `/` - Home/landing page
- `/login` - User login
- `/register` - User registration
- `/dashboard` - User dashboard (requires auth)

## Development Workflow

1. Services are located in `src/services/`
2. Pages are located in `src/pages/`
3. Use service hooks to access backend functionality:
   ```javascript
   const { authManager } = useAuth();
   const { apiClient } = useApi();
   ```
4. Follow TailwindCSS utility patterns for styling

## Contributing

When adding new features:

1. Create services in `src/services/` for business logic
2. Create pages in `src/pages/` organized by feature
3. Add routes in `App.jsx`
4. Use existing service patterns for consistency

## Backend Integration

This frontend is designed to work with the MaplePress backend API at:
`cloud/mapleopentech-backend`

The backend should be running on the URL specified in `VITE_API_BASE_URL`.

### Error Handling with RFC 9457

The frontend fully supports **RFC 9457 (Problem Details for HTTP APIs)** for error handling. The backend returns standardized error responses that are automatically parsed by `ApiClient`:

```json
{
  "type": "about:blank",
  "title": "Validation Error",
  "status": 400,
  "detail": "One or more validation errors occurred",
  "errors": {
    "email": ["Invalid email format"],
    "password": ["Password must be at least 8 characters"]
  }
}
```

**Key Features:**
- 🔄 Automatic error parsing in `ApiClient.js`
- 📋 Field-level validation errors preserved
- 🎯 User-friendly error messages
- 🔗 Consistent with backend error format

Services that handle validation errors:
- `RegisterService` - User registration with detailed field errors
- `SiteService` - WordPress site creation with domain validation
- All services inherit RFC 9457 parsing from `ApiClient`

See detailed documentation in [`docs/API/REGISTRATION_API.md`](./docs/API/REGISTRATION_API.md#error-handling) for examples.

## Documentation

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

### Architecture Documentation
- **[FRONTEND_ARCHITECTURE.md](./docs/FRONTEND_ARCHITECTURE.md)** - Complete architecture guide with three-layer service pattern
- **[ARCHITECTURE_SIMPLE.md](./docs/ARCHITECTURE_SIMPLE.md)** - Quick reference guide
- **[ACCESS_REFRESH_TOKEN_IMPLEMENTATION.md](./docs/ACCESS_REFRESH_TOKEN_IMPLEMENTATION.md)** - Token refresh implementation guide
- **[TOKEN_REFRESH_ANALYSIS.md](./docs/TOKEN_REFRESH_ANALYSIS.md)** - Token refresh analysis

### API Integration Documentation
All API integration guides are located in [docs/API/](./docs/API/):

- **[HEALTH_API.md](./docs/API/HEALTH_API.md)** - Backend health check and monitoring
- **[REGISTRATION_API.md](./docs/API/REGISTRATION_API.md)** - User registration implementation and API integration
- **[LOGIN_API.md](./docs/API/LOGIN_API.md)** - User login implementation and API integration
- **[REFRESH_TOKEN_API.md](./docs/API/REFRESH_TOKEN_API.md)** - Token refresh implementation with automatic session maintenance
- **[HELLO_API.md](./docs/API/HELLO_API.md)** - Hello endpoint for authentication testing
- **[ME_API.md](./docs/API/ME_API.md)** - User profile endpoint with role-based access helpers
- **[TENANT_API.md](./docs/API/TENANT_API.md)** - Tenant management for multi-tenant architecture
- **[USER_API.md](./docs/API/USER_API.md)** - User management with tenant context
- **[SITE_API.md](./docs/API/SITE_API.md)** - WordPress site management with API key handling
- **[ADMIN_API.md](./docs/API/ADMIN_API.md)** - Admin account management and lockout handling

## License

This application is licensed under the [**GNU Affero General Public License v3.0**](https://opensource.org/license/agpl-v3). See [LICENSE](../../LICENSE) for more information.

## Related Projects

- [MaplePress Backend](../../cloud/mapleopentech-backend) - Backend API
- [MaplePress WordPress Plugin](../../native/wordpress/maplepress-plugin) - WordPress integration
- [MapleFile](../../web/maplefile-frontend) - Encrypted file storage

## Support

Found a bug? Want a feature to improve MaplePress? Please create an [issue](https://codeberg.org/mapleopentech/monorepo/issues/new).