How yujitani/questory works
Project Type and Purpose
• QueStory is a full-stack, learning-focused application aimed at helping programming beginners (especially RUNTEQ students) practice SQL, ActiveRecord, and Ruby tasks through short, mobile-friendly interactive exercises.
• The README clearly delineates both frontend and backend responsibilities, along with various features such as user authentication, quest management, problem solving, feedback handling, and even marketing and SNS sharing modules.
File Structure – Architectural Implications
• Frontend and Routing:
– The Next.js “app” directory is the heart of your application. It includes nested routes for different learning modules (e.g., “active_record”, “ruby”, “sql”) as well as marketing, sign-in/sign-up pages, API endpoints, and a shared “layout.tsx” for global styling.
– Dynamic routing is evidenced by folders with “[id]” notation and subroutes (such as in “app/(main)/sql/(area)” and “app/(main)/ruby/[id]”). This indicates a component-based, page-driven approach typical of Next.js applications.
• Components & Hooks:
– The “components” and “app/hooks” directories contain reusable UI elements (buttons, headers, quiz components) and custom logic (e.g., randomShuffle, stageReducer, useAnswers) that enforce separation of concerns and modularity.
• Data & Business Logic:
– The “data” folder holds static sample data (areas, content, questions, quests, stages, words) which likely drives the interactive lessons.
– The “db” and “src/db” directories include migrations and schema definitions; note that there is also integration with Drizzle in the “drizzle” folder. This arrangement suggests that database interactions and migrations are well managed and versioned.
• API & Backend:
– Although the README mentions a Ruby/Ruby on Rails backend for user management and authentication, the repository holds “app/api” endpoints and even a “middleware.ts” file. This indicates either a hybrid approach (e.g., simulating backend functions within a Next.js API or existing integration with other technologies) or an intermediary service layer.
• External/Infrastructure Details:
– Configuration files like “next.config.mjs”, “docker-compose.yml”, “wrangler.toml”, and GitHub Action templates in “.github” highlight CI/CD, deployment, and infrastructure concerns, while Cloudflare Pages is noted for hosting.
A. Frontend Layer (Client Side)
– Next.js application that runs on user devices (emphasizing mobile usability).
– Represent key page groups: (main) content routes, marketing pages, authentication flows (sign-in/sign-up), and the dynamic learning modules (SQL, ActiveRecord, Ruby).
– Use separate blocks for the UI components (common UI elements, hooks, layout components) that support user interaction.
– Note integration with third-party authentication providers (OAuth, LINE, GitHub) for SNS login and sharing.
B. API Layer / Backend Logic
– Next.js API routes (e.g., “app/api/hello”) act as a bridge to the business logic.
– Even if the full Ruby on Rails backend is planned, emphasize that authentication and quest management endpoints (for CRUD operations on quests, stages, and problems) are emerging features.
C. Database & Data Persistence Layer
– Include a representation of the databases (MySQL or PostgreSQL as noted in the README) that store user data, quest details, and session logs.
– Show the involvement of database migrations (from the “db” and “src/db” folders) and the Drizzle ORM configuration.
– Illustrate how static data (from the “data” folder) may be used to seed or augment exercises.
D. External Components and Integrations
– Cloudflare Pages for deployment and hosting.
– CI/CD pipelines via GitHub Actions and Cloudflare Pages.
– External OAuth providers and SNS integrations (LINE, GitHub, etc.) for authentication and social sharing.
– Notification services (e.g., Line notifications for login streaks) may be shown as external endpoints.
Relationships and Interactions Between Components
– Data flow from the user’s browser (mobile or desktop) to the Next.js frontend.
– API calls from frontend components to the API layer for authentication, quest retrieval, and operation execution (CRUD).
– Interactions between the API/backend layer and the database for data persistence (user information, quest/problem records).
– Triggered events such as SNS sharing/notifications flowing outward to external services.
• That the API layer acts as the mediator for data validation and business logic before updating the database.
Architectural Patterns and Technology Use
• Component-Based UI: Emphasize the modularity of Next.js pages and React components, supported by directories like “components”, “hooks”, and well-organized routing in “app”.
• Dynamic Routing and Modular Design: Highlight how dynamic routes (with [id] parameters) are used to render varying content (e.g., different SQL challenges or ActiveRecord exercises).
• Configuration and infrastructure management: Show that CI/CD, database migrations, and Cloudflare deployment are integral to the system.