# yujitani/questory architecture

> Architecture diagram of the GitHub repository yujitani/questory, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yujitani/questory
- Repository: https://github.com/yujitani/questory

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Nodes
    UB["User Browser"]:::external

    %% Frontend Layer
    subgraph "Frontend (Next.js App)"
        f_root["App Root"]:::frontend
        f_main["Main Content & Learning Modules"]:::frontend
        f_active["ActiveRecord Module"]:::frontend
        f_ruby["Ruby Module"]:::frontend
        f_sql["SQL Module"]:::frontend
        f_marketing["Marketing Pages"]:::frontend
        f_auth["Authentication Pages (Sign-In/Up)"]:::frontend
        f_global1["Global Layout (Main)"]:::frontend
        f_global2["Global Layout (Marketing)"]:::frontend
        f_ui["Reusable UI Components"]:::frontend
        f_hooks["Custom Hooks & Client-Side Logic"]:::frontend

        f_root --> f_main
        f_main --> f_active
        f_main --> f_ruby
        f_main --> f_sql
        f_root --> f_marketing
        f_root --> f_auth
        f_root --> f_global1
        f_root --> f_ui
        f_root --> f_hooks
    end

    %% API / Backend Layer
    subgraph "API / Business Logic"
        api_endpoint["API Endpoints (/hello)"]:::backend
    end

    %% Database Layer
    subgraph "Database Layer"
        db_static["Static Data for Exercises"]:::database
        db_db["DB Migrations (db/)"]:::database
        db_drizzle["DB Migrations (drizzle/)"]:::database
        db_src["DB Migrations (src/db/)"]:::database
    end

    %% Infrastructure & External Services
    subgraph "Infrastructure & External Services"
        infra_cloud["Cloudflare Pages"]:::external
        infra_github["CI/CD (GitHub Actions)"]:::external
        infra_docker["Docker Compose"]:::external
        infra_next["Next.js Config"]:::external
        infra_wrangler["Wrangler Config"]:::external
        infra_oauth["OAuth/SNS Providers"]:::external
    end

    %% Connections
    UB --> f_root
    f_root -->|"API_Call"| api_endpoint
    api_endpoint -->|"Data_Persistence"| db_static
    api_endpoint --> db_db
    api_endpoint --> db_drizzle
    api_endpoint --> db_src
    f_auth -->|"Uses"| infra_oauth
    api_endpoint -->|"Integrates"| infra_cloud
    api_endpoint --> infra_github
    api_endpoint --> infra_docker
    api_endpoint --> infra_next
    api_endpoint --> infra_wrangler

    %% Class Definitions
    classDef frontend fill:#AED6F1,stroke:#3498DB,stroke-width:2px;
    classDef backend fill:#C39BD3,stroke:#8E44AD,stroke-width:2px;
    classDef database fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;

    %% Click Events for Component Mapping
    click f_root "https://github.com/yujitani/questory/tree/main/app/"
    click f_active "https://github.com/yujitani/questory/tree/main/app/(main)/active_record"
    click f_ruby "https://github.com/yujitani/questory/tree/main/app/(main)/ruby"
    click f_sql "https://github.com/yujitani/questory/tree/main/app/(main)/sql"
    click f_global1 "https://github.com/yujitani/questory/blob/main/app/layout.tsx"
    click f_global2 "https://github.com/yujitani/questory/blob/main/app/(marketing)/layout.tsx"
    click f_ui "https://github.com/yujitani/questory/tree/main/components/"
    click f_hooks "https://github.com/yujitani/questory/tree/main/app/hooks"
    click api_endpoint "https://github.com/yujitani/questory/blob/main/app/api/hello/route.ts"
    click db_db "https://github.com/yujitani/questory/tree/main/db/"
    click db_drizzle "https://github.com/yujitani/questory/tree/main/drizzle/"
    click db_src "https://github.com/yujitani/questory/tree/main/src/db/"
    click db_static "https://github.com/yujitani/questory/tree/main/data/"
    click infra_github "https://github.com/yujitani/questory/tree/main/.github/"
    click infra_docker "https://github.com/yujitani/questory/blob/main/docker-compose.yml"
    click infra_next "https://github.com/yujitani/questory/blob/main/next.config.mjs"
    click infra_wrangler "https://github.com/yujitani/questory/blob/main/wrangler.toml"
```
