monorepo/web/maplepress-frontend/docs/ARCHITECTURE_SIMPLE.md

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