How gyumong/chukchuk-haksa works
Project Type & Purpose
• This is a full-stack application designed to help students manage and verify their academic progress and graduation requirements by syncing data directly from the school portal.
• The project integrates real-time academic data synchronization, user authentication, and data crawling from external sources (e.g., using Playwright in the suwon-scrape module).
File Structure
• Notice the clear separation between the frontend (in the “app” directory with various route groups like (funnel), (landing), (main), (setting)) and backend logic (API endpoints in “app/api” paired with a robust server organization in the “server” folder).
• The “server” folder is structured following a clean or hexagonal architecture pattern with distinct layers:
• Application layer (use cases and services)
• Domain layer (models, repositories, and business rules)
• Infrastructure layer (implementations for external services like portal integrations and Supabase repositories)
• In addition, the “lib” folder centralizes shared libraries for authentication, crawling, and Supabase integration.
• Configuration files (e.g., next.config.mjs, tsconfig.json) and development tooling (ESLint, Prettier, GitHub workflows) are also present, ensuring quality and build automation.
Review README for Additional Insights
• The README confirms that the core functionalities include syncing academic data from the school portal and comparing it against graduation requirements.
• It also lists the technology stack where Next.js with React and TypeScript is used for the frontend, Node.js with Supabase (PostgreSQL) for the backend, and Playwright for data crawling.
• The project also involves deployment and monitoring via Docker, AWS ECS, Vercel, and Sentry.
a. Main Components to Include:
• Client / Browser: Users access the service through a web application.
• Frontend Application: The Next.js based React application, which manages various route segments (funnel, landing, main, setting) and UI components (found in directories like “components/ui” and “app/(main)/components”).
• API Layer: The Next.js API routes under “app/api” that expose endpoints for fetching academic data, dashboard information, graduation progress, and more.
• Server / Business Logic:
• Application Layer: Located in “server/application”, with use cases for student management, academic records synchronization, and user-related operations.
• Domain Layer: Consisting of models and repository interfaces in “server/domain/…”, encapsulating core business rules.
• Infrastructure Layer: Implementation details (Supabase integration, portal scraping integration) found in “server/infrastructure” provide bridges to data sources.
• External Services & Data Sources:
• Supabase/PostgreSQL: As the database backend and for authentication (noted in “lib/supabase” and server/infrastructure).
• School Portal & Crawling Services: External endpoints accessed via the “suwon-scrape” modules and crawling libraries (Playwright usage).
• Third-party Auth Services: Integration with providers like Kakao, as seen from files in “lib/auth” and “components/KakaoProvider.tsx”.
• Monitoring & Error Handling: Sentry configuration files for logging and error monitoring (sentry.*.config.ts).
b. Relationships and Data Flows:
• User actions in the browser pass through the React-based UI which communicates with the API endpoints (data fetching, user authentication, etc.).
• API endpoints translate these requests into business operations by invoking use cases in the application layer.
• The application layer interacts with the domain layer to enforce business rules, and then persists or retrieves data using the infrastructure layer which talks to Supabase/PostgreSQL.
• For dynamic academic data, the system triggers external crawling processes that connect to the school portal to update academic records.
• Authentication requests are routed through modules in both the frontend (via authentication components) and backend (through the domain and infrastructure auth services).