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:

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

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

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