How pieterbb/todostreak works
Main system components
• Client/Browser: Represents the user-facing layer, where users interact with the application.
• Next.js Frontend: The React-based UI built using Next.js (in the /src/app directory). This includes pages for todos, projects, topics, settings, profiles, etc. Distinguish between public pages, user profiles, and project pages.
• API Routes: Located under /src/app/api (for auth, projects, search, settings, todos, topics, users). These server-side endpoints handle data fetching, authentication workflows, and mutations.
• Database & ORM Layer: Prisma in the /prisma directory (with schema and seed files). This layer communicates with the Postgres database.
• External Services:
• Authentication Providers: NextAuth.js endpoints for social OAuth and magic link email authentication.
• Storage & Media: Cloudinary for image uploads.
• Email Service / SMTP server for sending authentication messages.
• (Optional) Third-party integrations such as Discord or Google OAuth.
• Utility Libraries & Hooks: Shared utilities in /src/lib and custom React hooks (in /src/hooks) that encapsulate business logic, state management via React Query, form handling, file uploads, etc.
• Configuration & Deployment: Files like next.config.js, Vercel integration snippets, Tailwind CSS configurations, and environment variable files (.env.example) that provide setup and deployment details.
Relationship and interactions
• The Browser communicates with the Next.js Frontend which renders the UI components. These components are built using React and styled with Tailwind CSS.
• When data is needed, the client makes calls (often via React Query and custom hooks) to the API routes. These API routes are internally structured under /src/app/api.
• The API routes use Prisma (via client code in /src/lib) to read from/write to the Postgres database.
• Authentication requests are handled by NextAuth.js (in /src/app/api/auth/...), which also interacts with external authentication providers (social OAuth, SMTP for magic links).
• Media uploads (e.g., user avatars, project images) integrate with Cloudinary.
• Additionally, utility hooks and components are shared across various parts of the frontend, ensuring modularization and reuse.
Architectural patterns and design principles
• Separation of Concerns: The structure clearly separates UI components, API endpoints, authentication logic, database interactions, and external services.
• Modular & Scalable: The directory organization (with different APIs for features like todos, projects, topics) indicates a modular design that can be extended as new features (e.g., forum enhancements or advanced notifications) are added.
• Use of Client and Server Components: With the Next.js app directory architecture, differentiate between components that run on the server and those on the client.
• Integration of Modern Libraries: Use of React Query for asynchronous server state and Zod for validation enforces type safety throughout the stack.
Including relevant technologies
• Next.js (React-based UI with Server and API routes)
• NextAuth.js for authentication flows
• Prisma as the ORM connecting to a Postgres database
• Tailwind CSS for styling
• React Query, React Hook Form, Zod for client-side data flow, form processing, and validations
• Cloudinary integration for media uploads
Elements
• Browser / Client
• Next.js Frontend (with nested UI components: pages, layouts, and widgets)
• API Server (highlight different sub-components like Auth API, Todos API, Projects API, Topics API)
• Database (Postgres via Prisma)
• External Services (Authentication Providers, SMTP, Cloudinary, optional third-party APIs like Discord/Google)
• Data/request flows from the Browser to the Frontend.
• API requests from the Frontend to the Backend (API routes) and responses back.
• Database queries from API endpoints to the Database.
• External calls from the API endpoints to third-party authentication services or media storage.
• Or add notes for key middleware logic such as authentication flows and data validations.