How far0uq/pos works
Project type and purpose
• This is a Next.js full-stack web application.
• Purpose: provide a product browser and cart checkout UI for Square sellers. It handles seller OAuth, product/category/discount/tax lookups via Square’s Costa API, manages a shopping cart, and stores session or cart state in Redis.
File structure
• Top-level configs: .env, next.config.mjs, Tailwind, PostCSS, TypeScript, Sentry configs, Jest setup.
• __tests__ / __mocks__: unit tests for UI components and API logic.
• constants/, types/: shared constants and TypeScript interfaces.
• src/app/
– app/api: Next.js Serverless API routes grouped by feature (auth, cartAPI, categoriesAPI, discountsAPI, productsAPI, taxAPI, authTokenAPI, sentry-example-api).
– app/auth & app/auth/loading: NextAuth UI pages.
– app/clientAPI: client wrappers (authAPI, modifiersAPI, orderAPI, productAPI).
– app/hooks: React hooks (data fetching via React-Query or custom fetch) and form submission logic.
– app/layout.tsx & app/page.tsx: root layouts and pages.
– app/mainpage & components: UI tree for product browser, search bar, cart UI.
– app/store: Redux slice for cart or central state.
– app/wrapper: QueryClientWrapper for React-Query global provider.
• public/: static assets.
• middleware.ts: Next.js middleware for auth/session logic.
README for additional insights
• Describes OAuth flow for Square Seller.
• Mentions runtime dependency on Redis and the Costa API server.
• Outlines core functionality: auth, search, product listing.
a. Main components
1. Browser / Client
– Next.js React UI (app/pages + components)
– React Query + custom hooks
– Redux Toolkit store (cartSlice)
2. Next.js Server (app/api routes + middleware)
– Auth endpoints (NextAuth + custom token API)
– Feature APIs (cartAPI, categoriesAPI, discountsAPI, productsAPI, taxAPI)
– Session & state management (Redis)
– Sentry instrumentation (client, edge, server)
3. External Services
– Square’s Costa API (OAuth, products, categories, discounts, taxes)
– Redis (session, cart persistence)
b. Relationships & data flow
• Client UI triggers data fetch → hits Next.js API route → route handler calls Costa API or Redis → returns data JSON → React Query / hooks update Redux store → UI re-renders.
• OAuth flow: UI → NextAuth route → Square OAuth server → callback to NextAuth API route → session persisted in Redis.
• On cart operations: UI dispatches Redux action or uses mutation hook → calls cartAPI → updates cart in Redis → returns updated cart.
c. Architectural patterns & principles
• “App router” folder structure in Next.js 13 (layout/page vs. server/client components)
• Layered separation: UI layer, API layer, external integrations, persistence layer
• Use of React Query for server state, Redux for local cart state
• NextAuth for authentication, Redis-backed session store
d. Key technologies & libraries
• Next.js 13 (app directory, serverless functions)
• React Query (QueryClientWrapper)
• Redux Toolkit (cartSlice)
• NextAuth.js (OAuth)
• Redis (session & caching)
• Square Costa API
• Sentry (observability)
• Jest & React Testing Library