Initial commit: Open sourcing all of the Maple Open Technologies code.
This commit is contained in:
commit
755d54a99d
2010 changed files with 448675 additions and 0 deletions
237
web/maplepress-frontend/README.md
Normal file
237
web/maplepress-frontend/README.md
Normal file
|
|
@ -0,0 +1,237 @@
|
|||
# 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).
|
||||
Loading…
Add table
Add a link
Reference in a new issue