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
224
web/maplepress-frontend/docs/ARCHITECTURE_SIMPLE.md
Normal file
224
web/maplepress-frontend/docs/ARCHITECTURE_SIMPLE.md
Normal file
|
|
@ -0,0 +1,224 @@
|
|||
# MaplePress Frontend Architecture
|
||||
|
||||
This document describes the architecture and organization of the MaplePress React frontend application.
|
||||
|
||||
## Overview
|
||||
|
||||
The MaplePress frontend is built with React 19, Vite, and TailwindCSS, following a clean separation of concerns with a service layer pattern similar to the maplefile-frontend architecture.
|
||||
|
||||
## Technology Stack
|
||||
|
||||
- **React 19** - UI framework
|
||||
- **Vite** - Build tool and dev server
|
||||
- **TailwindCSS 4** - Utility-first CSS framework
|
||||
- **react-router** - Client-side routing
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
src/
|
||||
├── services/ # Service layer (business logic)
|
||||
│ ├── Manager/ # Manager services (orchestration)
|
||||
│ │ └── AuthManager.js
|
||||
│ ├── API/ # API client services
|
||||
│ │ └── ApiClient.js
|
||||
│ └── Services.jsx # Service registry and DI container
|
||||
│
|
||||
├── pages/ # Page components
|
||||
│ ├── Home/ # Home/landing page
|
||||
│ │ └── IndexPage.jsx
|
||||
│ ├── Auth/ # Authentication pages
|
||||
│ │ ├── Login.jsx
|
||||
│ │ └── Register.jsx
|
||||
│ └── Dashboard/ # Dashboard pages
|
||||
│ └── Dashboard.jsx
|
||||
│
|
||||
├── hooks/ # Custom React hooks (future)
|
||||
├── App.jsx # Main app component with routing
|
||||
└── main.jsx # Application entry point
|
||||
```
|
||||
|
||||
## Architecture Layers
|
||||
|
||||
### 1. Service Layer (`src/services/`)
|
||||
|
||||
The service layer provides a clean separation between UI components and business logic, following dependency injection principles.
|
||||
|
||||
**Key Files:**
|
||||
- `Services.jsx` - Central service registry with React Context
|
||||
- `Manager/AuthManager.js` - Authentication manager
|
||||
- `API/ApiClient.js` - HTTP client for backend API
|
||||
|
||||
**Service Pattern:**
|
||||
```javascript
|
||||
// Services are created with dependency injection
|
||||
const authManager = new AuthManager();
|
||||
const apiClient = ApiClient;
|
||||
|
||||
// Services are provided via React Context
|
||||
<ServiceProvider>
|
||||
{/* App components */}
|
||||
</ServiceProvider>
|
||||
|
||||
// Components access services via hooks
|
||||
const { authManager } = useAuth();
|
||||
```
|
||||
|
||||
### 2. Pages (`src/pages/`)
|
||||
|
||||
Page components represent full-page views. Each page is organized by feature:
|
||||
|
||||
- **Home/** - Landing page with navigation to auth
|
||||
- **Auth/** - Login and registration pages
|
||||
- **Dashboard/** - User dashboard and management
|
||||
|
||||
### 3. Routing (`src/App.jsx`)
|
||||
|
||||
Centralized routing configuration using react-router:
|
||||
|
||||
```javascript
|
||||
<Routes>
|
||||
{/* Public routes */}
|
||||
<Route path="/" element={<IndexPage />} />
|
||||
<Route path="/login" element={<Login />} />
|
||||
<Route path="/register" element={<Register />} />
|
||||
|
||||
{/* Protected routes */}
|
||||
<Route path="/dashboard" element={<Dashboard />} />
|
||||
</Routes>
|
||||
```
|
||||
|
||||
## Service Layer Details
|
||||
|
||||
### AuthManager
|
||||
|
||||
Manages authentication state and operations:
|
||||
|
||||
- `initialize()` - Initialize auth manager
|
||||
- `isAuthenticated()` - Check if user is logged in
|
||||
- `login(email, password)` - User login
|
||||
- `register(email, password, name)` - User registration
|
||||
- `logout()` - User logout
|
||||
- `getAccessToken()` - Get current access token
|
||||
- `getUser()` - Get current user data
|
||||
|
||||
### ApiClient
|
||||
|
||||
Handles HTTP communication with the backend:
|
||||
|
||||
- `get(endpoint, options)` - GET request
|
||||
- `post(endpoint, body, options)` - POST request
|
||||
- `put(endpoint, body, options)` - PUT request
|
||||
- `patch(endpoint, body, options)` - PATCH request
|
||||
- `delete(endpoint, options)` - DELETE request
|
||||
|
||||
Automatically handles:
|
||||
- Authorization headers
|
||||
- JSON serialization
|
||||
- Error handling
|
||||
|
||||
### Service Hooks
|
||||
|
||||
Custom hooks provide easy access to services:
|
||||
|
||||
```javascript
|
||||
// Get all services
|
||||
const services = useServices();
|
||||
|
||||
// Get auth services
|
||||
const { authManager } = useAuth();
|
||||
|
||||
// Get API client
|
||||
const { apiClient } = useApi();
|
||||
```
|
||||
|
||||
## Page Components
|
||||
|
||||
### IndexPage (Home)
|
||||
- Landing page with MaplePress branding
|
||||
- Navigation to login/register
|
||||
- Feature highlights
|
||||
- Responsive design with TailwindCSS
|
||||
|
||||
### Login
|
||||
- Email/password authentication form
|
||||
- Form validation
|
||||
- Error handling
|
||||
- Navigation to register and home
|
||||
|
||||
### Register
|
||||
- User registration form
|
||||
- Password confirmation
|
||||
- Password strength validation
|
||||
- Navigation to login and home
|
||||
|
||||
### Dashboard
|
||||
- Protected route (requires authentication)
|
||||
- User welcome section
|
||||
- Stats display (sites, indexes, API requests)
|
||||
- Quick action buttons
|
||||
- Getting started guide
|
||||
|
||||
## State Management
|
||||
|
||||
Currently using React Context for service layer dependency injection. Future expansions may include:
|
||||
- Local component state with `useState`
|
||||
- Form state management
|
||||
- Potential integration with Redux/Zustand if needed
|
||||
|
||||
## Styling
|
||||
|
||||
Using TailwindCSS 4 utility classes for styling:
|
||||
- Responsive design with mobile-first approach
|
||||
- Consistent color scheme (indigo/blue palette)
|
||||
- Shadow and border utilities for depth
|
||||
- Hover states and transitions
|
||||
|
||||
## Development Workflow
|
||||
|
||||
1. **Start dev server**: `npm run dev`
|
||||
2. **Build for production**: `npm run build`
|
||||
3. **Lint code**: `npm run lint`
|
||||
4. **Preview build**: `npm run preview`
|
||||
|
||||
## API Integration
|
||||
|
||||
The ApiClient is configured to communicate with the MaplePress backend:
|
||||
|
||||
- Base URL: `VITE_API_BASE_URL` environment variable (default: `http://localhost:8000`)
|
||||
- Authentication: Bearer token in Authorization header
|
||||
- Content-Type: `application/json`
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
Current implementation provides stubs for:
|
||||
- [ ] Actual backend API integration
|
||||
- [ ] Token storage and refresh logic
|
||||
- [ ] Protected route guards
|
||||
- [ ] User profile management
|
||||
- [ ] API key management
|
||||
- [ ] Site management
|
||||
- [ ] Search index configuration
|
||||
- [ ] Analytics dashboard
|
||||
|
||||
## Testing
|
||||
|
||||
Testing structure to be implemented:
|
||||
- Unit tests for services
|
||||
- Component tests for pages
|
||||
- Integration tests for workflows
|
||||
- E2E tests for critical paths
|
||||
|
||||
## 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 service hooks to access backend functionality
|
||||
5. Follow TailwindCSS utility patterns for styling
|
||||
6. Keep components focused and single-responsibility
|
||||
|
||||
## References
|
||||
|
||||
This architecture is based on the maplefile-frontend pattern, adapted for MaplePress requirements.
|
||||
Loading…
Add table
Add a link
Reference in a new issue