POS Application

Scope

Explore Square POS APIs

Authentication

• Implement OAuth-based login using Square’s authentication system.
• Utilize NextAuth.js for handling authentication:
• Configure NextAuth to work with Square’s OAuth provider.
• Set up NextAuth API routes and handle callbacks.
• Implement session management using NextAuth’s built-in functionality.
• Ensure proper SSR authentication:
• Use NextAuth for server-side authentication checks.
• Implement client-side authentication state management using NextAuth’s useSession hook.
• Set up protected routes and API endpoints using NextAuth middleware.
• Implement secure logout functionality.

Product Listing

• The homepage should display a list of products using Server-Side Rendering (SSR).
• Implement streaming UI for product added cart to improve perceived performance.
• Each product card should show:
  • Name
  • Price
  • Image
  • “Add to Cart” button
• Allow users to increase or decrease product quantity directly on the card.
• After clicking “Add to Cart,” replace the button with quantity controls (+/- buttons).

Checkout Management

1. Users should be able to add products to their cart.

2. The cart should be accessible from a side drawer, showing a list of added items.

3. Quantity can be changed from the cart for any individual product

4. Discounts

   1. Users should have the option to apply discounts to individual items or the entire order.
   2. Discounts should be retrieved from an API and displayed as options during the checkout process.
   3. The application should recalculate the order amount dynamically when discounts are applied.

5. Taxes

   1. Users should be able to toggle taxes on/off for individual items or the entire order to see the amounts with and without taxes.
   2. Tax options should be retrieved from an API and displayed during the checkout process.
   3. The application should recalculate the order amount dynamically when tax settings are changed.

Payment Processing

• Display a summary of selected items, applied discounts, and taxes in the checkout.
• Implement order calculation using Next.js server actions.
• Provide a button to confirm and place the order.
• Handle order confirmation and display appropriate success messages.

Implementation Guidelines

Square POS Integration

• Use Next.js server actions to integrate directly with Square POS APIs.
• Implement functions for product retrieval, discount and tax options, and order processing.
• Ensure Square API calls are made securely using authenticated sessions.

User Interface

• Ensure the UI is responsive and provides a seamless experience across devices.
• Use appropriate loading indicators (e.g., spinners, skeletons) during data fetching.
• Implement a consistent UI for login/logout functionality.

Server-Side Rendering (SSR)

• Implement SSR for the homepage product listing.
• Use streaming UI concepts for products added to the cart to improve initial load times.
• Utilize NextAuth for authentication checks in SSR pages.

Error Handling

• Implement error boundaries for the SSR page to gracefully handle rendering errors.
• Provide meaningful error messages and fallback UI for various error scenarios.
• Handle authentication errors gracefully, redirecting to login when necessary.

Code Structure

• Organize code modularly, following Next.js best practices.
• Centralize NextAuth configuration and custom hooks for authentication.

Security

• Leverage NextAuth’s built-in security features for token handling and session management.
• Implement additional security measures to protect against common web vulnerabilities.
• Ensure secure handling of Square API credentials and tokens.

Implementation

Phase 1: Setup and Authentication

Tasks:

1. Set up the Next.js project with TypeScript.
2. Configure Ant Design (antd) UI library and AntD tokens.
3. Set up linting and build scripts.
4. Implement NextAuth.js for authentication:
5. Configure Square OAuth provider.
6. Set up NextAuth API routes and callbacks.
7. Implement protected routes using NextAuth middleware.
8. Create login/logout UI components.

Expectations:

• Project structure follows Next.js best practices for TypeScript projects.
• Ant Design components are properly configured and themed using design tokens.
• ESLint and Prettier are set up with appropriate rules.
• NextAuth is fully integrated with Square OAuth:
• Users can log in and out seamlessly.
• Protected routes are properly secured.
• Server-side and client-side authentication checks are implemented.
• Login/logout UI is intuitive and responsive.

Phase 2: Product Listing and Cart

Tasks:

1. Create an intuitive UI to list down all the products coming from square.
2. Implement product search and filtering functionality.
3. Develop the shopping cart as a side drawer.
4. Use Tanstack react query for data fetching and caching.

Expectations:

• Homepage renders server-side for optimal performance.
• Create a custom product card component using AntD tokens.
• Product search and filtering are fast and accurate.
• Shopping cart uses streaming UI for improved perceived performance.
• React Query is properly implemented for efficient data management.
• All operations are secure and respect the user’s authentication status.
• Implement well-defined component patterns (container/layout/UI) and use composition to build a modular and maintainable codebase.
• No global state management library is used; rely on React’s built-in state management and context API if necessary.

Refactor the codebase to separate side-effects and API calls from components.

Explore use of AntD-Style

Phase 3: Checkout Process

Tasks:

1. Implement the checkout process with discounts and taxes.
2. Create custom hooks for business logic (e.g., applying discounts/taxes).

Expectations:

• Checkout process is smooth and intuitive.
• Discounts and taxes are correctly applied and calculated.
• Create at least one discount item that can be applied to only one specific variant of the item.
• Custom hooks encapsulate complex business logic, making it reusable and testable.
• Follow immutability practices consistently throughout the application to ensure data integrity and predictable behavior.
• State management relies on React’s built-in features (useState, useReducer) rather than external libraries.

Phase 4: Optimization and Testing

Tasks:

1. Utilize a third-party library, such as Zustand, to move local state management logic to a global state.
2. Implement error boundaries for the SSR page.
3. Optimize performance using Next.js image optimization and other techniques.
4. Write unit tests for key components, including NextAuth integration.
5. Develop end-to-end tests for critical user journeys, including login/logout flows.
6. Perform security audit, focusing on authentication and API integrations.

Expectations:

• Error boundaries gracefully handle and log SSR errors.

• Images are optimized for different devices and network conditions.

• Key components have comprehensive unit tests with good coverage.

• End-to-end tests cover all critical user flows, ensuring a robust user experience.

• Security audit reveals no critical vulnerabilities; any found issues are addressed promptly.

• Performance metrics (Core Web Vitals) meet or exceed industry standards.

Tip

Explore middleware in Next

Explore ImmerJs NextJs image optimization

Develop understanding of web vitals

Additional Considerations

• Explore advanced NextAuth features like callbacks and events for custom behavior.

• Implement proper error logging and monitoring (e.g., Sentry integration).

• Ensure adherence to Web Vitals for optimal performance.

• Regularly review and update NextAuth configuration to adhere to best practices.

Extra’s

• Signals
• Forms API in Ant Design