How alexsantosdev/open-pos works
Project type and purpose
• This is a full-stack Next.js application used to manage and display merchant inventory and sales, integrate subscription billing (Stripe), and handle authentication (NextAuth + Firebase). The frontend and backend coexist in the same codebase via Next.js pages and API routes.
File structure
• Top-level:
• next.config.js, package.json, tsconfig.json → build/config
• src/
– components/ → reusable React UI components (Alert, Modal, Table, etc.)
– hooks/ → custom React hooks (useTable)
– pages/ → Next.js pages (UI) + nested API routes (backend)
• pages/index.tsx, pages/[param].tsx → public-facing pages
• pages/admin/... → merchant dashboard (inventory, sales)
• pages/api/ → serverless functions (auth, subscribe, webhooks)
– services/ → wrappers/clients for external systems (api.ts, firebase.ts, stripe.js/ts)
– styles/, utils/ → global styles and utility functions
• Presence of .scss modules everywhere indicates CSS-module styling per component/page.
• API routes under src/pages/api represent the backend surface.
README for additional insights
• Purpose: development server, hot-reload, API route mapping.
a. Main Components
• Client (Browser)
• Next.js Server (Vercel or Node)
• Pages (SSR/SSG/CSR entry points)
• API Routes (serverless functions)
• Services Layer
• Firebase (Auth & Database)
• Stripe (Billing & Webhooks)
• Data Stores
• Firestore / Realtime DB (implied by firebase.ts)
• Stripe’s backend
• External Identity Provider (NextAuth providers)
b. Relationships & Interactions
1. Client → Next.js Pages: HTTP(S) requests for UI (SSR or static).
2. Pages render React components; use services/api.ts for client-side data fetching (CSR).
3. Client calls /api/* endpoints for protected actions:
• /api/auth/[...nextauth] → NextAuth handshake → Firebase Auth
• /api/subscribe → Stripe subscription creation
• /api/webhooks → Stripe webhook events → manageSubscription
4. API Routes → Services → External Systems:
• Firebase SDK in services/firebase.ts (CRUD merchant data)
• Stripe SDK in services/stripe.ts (charge, subscription)
5. External Systems send events (e.g., Stripe webhook) back to API Routes.
c. Architectural Patterns & Design Principles
• Separation of concerns:
• UI (components/)
• State & side-effects (hooks/, services/)
• Data/API surface (pages/api/)
• Server-Side Rendering (SSR) and Client-Side Rendering (CSR) via Next.js.
• Serverless functions as micro-backends (API routes).
• Modular SCSS for scoped styling.
d. Key Technologies & Frameworks
• Next.js (SSR/SSG/CSR + API routes)
• React + TypeScript
• NextAuth.js for authentication
• Firebase SDK (Authentication + Firestore)
• Stripe SDK (Payments & Webhooks)
• SCSS Modules