monorepo/web/maplepress-frontend/README.md

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

# Install dependencies
npm install

# Copy environment variables
cp .env.example .env

# Edit .env and configure your backend API URL

Development

# Start development server
npm run dev

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

Building

# Build for production
npm run build

# Preview production build
npm run preview

Linting

# 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 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:

# 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:

   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:

{
  "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 for examples.

Documentation

Comprehensive documentation is available in the docs/ directory:

Architecture Documentation

• FRONTEND_ARCHITECTURE.md - Complete architecture guide with three-layer service pattern
• ARCHITECTURE_SIMPLE.md - Quick reference guide
• ACCESS_REFRESH_TOKEN_IMPLEMENTATION.md - Token refresh implementation guide
• TOKEN_REFRESH_ANALYSIS.md - Token refresh analysis

API Integration Documentation

All API integration guides are located in docs/API/:

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

License

This application is licensed under the GNU Affero General Public License v3.0. See LICENSE for more information.

Related Projects

• MaplePress Backend - Backend API
• MaplePress WordPress Plugin - WordPress integration
• MapleFile - Encrypted file storage

Support

Found a bug? Want a feature to improve MaplePress? Please create an issue.