How welllucky/services works
Project type and purpose
• This is a full-stack, service-desk/helpdesk web application called “Services,” built with Next.js 14 (React) on the front end and Node/TypeORM/MySQL behind the scenes via Next API Handlers.
• It streamlines ticket creation in three steps (describe issue, add evidence, confirm) and hides complexity (automatically assigns sector, priority, etc.).
File structure
• Frontend (UI & routing) lives under src/app (Next.js App Router), src/screens, src/components, src/assets, src/styles, and Storybook docs under .storybook & src/docs.
• Backend API logic is in Next API Routes (src/app/api/...) and a separate src/server folder containing controllers, functions (auth, config, protectController, etc.), and the server entrypoint.
• Shared abstractions & implementations:
• “implementations/client” & “implementations/server” for DI layers (Analytics, HttpClient, JWT, Crypto, FeatureFlag, Firebase, Messaging).
• src/utils/providers and src/utils/stores for React context/Zustand state management.
• Types & DTOs under src/types.
• Config and environment files: next.config.js, .env, sentry configs, deepsource, ESLint, Prettier, CI workflows, Playwright tests, and Vercel deployment (vercel.json).
Main components
a. Frontend (Next.js App)
• Pages & Layout (src/app)
• UI Components & Screens (src/components, src/screens)
• Resource Providers & State Stores (src/utils/providers, src/utils/stores)
• Client Abstractions & Infra (Analytics, HttpClient, FeatureFlag, Messaging, Firebase)
b. Backend/API (Next API Routes + custom server logic)
• Route Handlers (src/app/api/…)
• Controller Layer (src/server/controllers)
• Business Functions (src/server/functions: auth, getEnv, protect, revalidate)
• Infrastructure Abstractions (Crypto, JWT, Http) & Agents (implementations/server/infra)
c. Persistence Layer
• TypeORM Entities & MySQL Database (configured via env vars)
d. External Services
• Sentry (Error monitoring)
• Firebase (Push messaging / Remote config / Feature flags)
• Analytics (e.g., Google Analytics or custom via abstractions)
e. CI/CD & Testing
• Playwright E2E & Jest/RTL unit tests
• GitHub Actions workflows and Deepsource scanning
• Storybook documentation
Relationships & data flow
• User interacts with Frontend UI (React)
• UI calls HttpClient to send REST requests to Next.js API Routes
• API route maps to Controller → calls business functions → uses infra agents (Crypto/JWT) → accesses MySQL via TypeORM
• Controllers return JSON to UI; UI updates state via Providers/Zustand
• Frontend sends telemetry to Analytics and error logs to Sentry asynchronously
• Push notifications via Firebase Messaging SW
Architectural patterns & design principles
• Layered architecture: Presentation (pages/screens), Service (controllers/functions), Data (ORM/DB)
• Dependency inversion via Abstractions/Implementations (IoC pattern)
• Provider pattern in React for cross-cutting concerns (Auth, Feature Flags, Services)
• Next.js App Router for file-based routing and SSR/SSG
• Separation of concerns: UI vs. business logic vs. infrastructure
Detail level & essential elements
• Don’t over-aggregate: Show meaningful subcomponents (e.g., HttpClient vs. FeatureFlag infra)
• DI/Provider boundaries to illustrate how abstractions map to concrete implementations
• Next.js file-based router as the entry point for both pages and API endpoints
• Environment variables/configuration layer (DB, Sentry, Firebase) is visible