mapleopentech/monorepo
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
monorepo/web/maplepress-frontend/README.md

237 lines
7.3 KiB
Markdown
Raw Blame History

# 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).
Reference in a new issue View git blame Copy permalink