How g-ohara/curlarc-web works
<explanation>
1. Identify the project type and purpose
- CurlARC‑Web is the frontend of a full‑stack, web‑based curling match recording and management system.
- Built with Next.js and React, it handles user authentication, dynamic routing for teams and match records, and communicates with a separate backend service (dyoshyy/CurlARC‑Service).
2. Analyze the file structure
- Top‑level “app” directory: Next.js App Router with dynamic routes ([teamId], [recordId])
• page.tsx files define layouts and page entrypoints
• components under each route folder (e.g., sheet buttons, scoreBoard) implement UI
• serverActions.tsx for Next.js 13 Server Actions
- “app/api/auth/[...nextauth]/route.ts”: NextAuth API route for OAuth/session management
- “lib/api” and “utils/api”: client wrappers for calling the backend service (REST)
- “components” and “app/components”: reusable UI elements and global layout (header, footer, UI primitives)
- Configuration: next.config.mjs, tailwind.config.ts, tsconfig.json
- “firebaseConfig.js”: Firebase setup (if used for analytics or real‑time features)
- Public/static assets and global styles (globals.css)
3. Key insights from README
- Frontend: Next.js, React, Tailwind CSS (with CSS Modules/Styled Components)
- Authentication: NextAuth (OAuth flows)
- Hosting: Vercel for frontend; backend is Node.js serverless on Fly.io
- Real‑time match recording, team collaboration, REST API integration with backend
4. Main components & their interactions
a. User’s Browser (Client)
• Interacts with Next.js pages (SSR, SSG, or CSR)
• Executes client components for UI and fetches data via Next.js server actions or REST calls
• Manages session cookies/JWT via NextAuth
b. Next.js Frontend (Vercel Host)
• App Router handles routing: / (landing), /profile, /[teamId], /[teamId]/[recordId]
• NextAuth API route (/api/auth) for login/logout/session
• Server Actions (serverActions.tsx) & client APIs in lib/api
• Static assets served from /public
c. CurlARC Backend Service (Fly.io)
• Exposes REST endpoints: /teams, /records, /users, /auth (if delegated)
• Business logic for match storage, team management
• Database (e.g., PostgreSQL, MongoDB)
d. External Services
• OAuth Providers (Google, etc.) via NextAuth
• Potential Firebase services (from firebaseConfig.js)
5. Architectural patterns & design principles
- Separation of Concerns: UI components vs. data‑fetching wrappers vs. authentication
- Dynamic Routing: Next.js App Router for nested routes and layouts
- Server‑Side & Client‑Side Blend: Server Actions for secure ops, client components for interactivity
- API Layer Abstraction: lib/api and utils/api modules decouple HTTP calls from UI logic
6. Guidelines for drawing the diagram
a. Components to include (each as a separate shape):
1. Browser (User)
2. Vercel CDN & Edge (static assets)
3. Next.js Frontend
- App Router (dynamic pages)
- NextAuth API Route
- Server Actions
- UI Components Library
4. lib/api & utils/api wrappers
5. CurlARC‑Service Backend
- REST API Layer
- Database
6. External OAuth Provider(s)
7. (Optional) Firebase services
b. Relationships and data flows (use directional arrows):
- Browser → Next.js pages (HTTP/HTTPS)
- Next.js pages ↔ lib/api wrappers → Backend REST API
- Next.js API route (/api/auth) ↔ OAuth Provider → NextAuth session store
- Backend API ↔ Database
- Browser ↔ Firebase (if used)
c. Architectural patterns:
- Indicate Server‑Side Rendering (SSR) vs. Client‑Side Rendering (CSR) lanes
- Highlight use of Server Actions for secure, server‑only logic
- Show dynamic routing tree for /[teamId] and /[teamId]/[recordId]
d. Technologies & frameworks: label each component with its main tech (e.g., Next.js, React, Tailwind, Node.js, PostgreSQL)
7. Diagram styling recommendations
- Use clear labels on each box
- Color code by layer:
• Blue for Frontend (Next.js, UI components)
• Green for Backend (CurlARC‑Service, DB)
• Orange for External Services (OAuth, Firebase)
- Use solid arrows for primary data flow (e.g., API calls) and dashed arrows for secondary flows (e.g., auth token exchange)
- Group related components inside containers or swimlanes (e.g., “Vercel Frontend,” “Fly.io Backend”)
8. Tailoring to CurlARC‑Web
- Emphasize the App Router’s nested dynamic routes and component breakdown under app/[teamId]/[recordId]
- Show how NextAuth integrates via app/providers/NextAuth.tsx and the API route
- Illustrate the call chain from a UI action (e.g., “SaveRecordButton”) → serverAction or lib/api → backend → DB → back
By following these steps, you’ll produce a detailed, accurate system design diagram that captures all essential architectural elements of CurlARC‑Web.
</explanation>