DOCSEARCHbyAlgolia
Submit Docs

familytree

repository·main·Indexed 20 days ago

https://github.com/qiaoshouqing/familytree

A family tree visualization tool built with Next.js that allows users to manage and display multi-generational family histories through a structured JSON configuration. It includes features for authentication, generation-based data organization, and a search interface with filtering capabilities.

Tokens
7.4K
Snippets
30
Records
38
Agent score
67%

What's inside familytree

  1. Configure authentication modes

    main

    The project supports two authentication modes via the AUTH_MODE environment variable:

    • all: Allows all family members to access the site.
    • specific: Only allows users who enter a specific name (defined by SPECIFIC_NAME) to access the site.

  2. Generate family JSON data using AI

    main

    You can use AI (ChatGPT, Claude, DeepSeek, etc.) to convert unstructured family history into the required family-data.json format.

    Prompt Template for AI:

    Please organize the family information I provide into the following JSON format:
{
  "generations": [
    {
      "title": "Xth Generation",
      "people": [
        {
          "id": "unique-identifier",
          "name": "Name",
          "info": "Detailed information",
          "fatherId": "Father's ID",
          "birthYear": birth year,
          "deathYear": death year
        }
      ]
    }
  ]
}

Requirements:
1. Generate a unique id for each person (such as first-gen-1, second-gen-2, etc.)
2. Correctly set fatherId to establish parent-child relationships
3. Categorize people by generation
4. Include spouse, achievements, etc. in the info field
5. Use birthYear and deathYear to record birth and death years (if available)
6. Ensure the JSON format is valid and can be directly imported into the system

    Workflow:

    1. Prepare your text-based family history.
    2. Provide the prompt above along with your text to the AI.
    3. Copy the resulting JSON into config/family-data.json.
    4. Verify that fatherId links correctly to existing id values.
    {
  "generations": [
    {
      "title": "Xth Generation",
      "people": [
        {
          "id": "unique-identifier",
          "name": "Name",
          "info": "Detailed information",
          "fatherId": "Father's ID",
          "birthYear": birth year,
          "deathYear": death year
        }
      ]
    }
  ]
}

  3. Install and run the Family Tree project

    main

    To get started with the Family Tree visualization project, follow these steps to install dependencies and launch the development server.

    1. Install Dependencies

    Use your preferred package manager to install the required modules:

    npm install
# or
yarn install
# or
pnpm install
# or
bun install

    2. Run the Development Server

    Start the Next.js development server:

    npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

    Once running, visit http://localhost:3000 to view your family tree.

    npm install
npm run dev

  4. Configure authentication and project settings via environment variables

    main

    The project uses environment variables for authentication and global settings. First, create your local environment file:

    cp .env.local.example .env.local

    Edit .env.local to configure the following keys:

    KeyDescription
    NEXT_PUBLIC_REQUIRE_AUTHSet to true or false to enable/disable login authentication.
    AUTH_MODEDefines how users are allowed in. Use all to allow all family members, or specific to restrict access to certain names.
    SPECIFIC_NAME(Used when AUTH_MODE=specific) The specific login name allowed to access the site.
    NEXT_PUBLIC_FAMILY_NAMEThe surname used for the website title, description, and footer.
    PORTThe application port (e.g., 3000).
    NEXT_PUBLIC_REQUIRE_AUTH=false
AUTH_MODE=specific
SPECIFIC_NAME=白景琦
NEXT_PUBLIC_FAMILY_NAME=白
PORT=3000

  7. Add family data via JSON

    main

    Family data is managed by creating or editing a family-data.json file in the config directory. The data is organized by generations, where each person is linked to their father via a fatherId to establish lineage.

    {
  "generations": [
    {
      "title": "第一世",
      "people": [
        {
          "id": "person-id",
          "name": "姓名",
          "info": "人物描述",
          "fatherId": "父亲ID",
          "birthYear": 1900,
          "deathYear": 1980
        }
      ]
    }
  ]
}

  9. Configure authentication and family settings via environment variables

    main

    The project uses environment variables to configure authentication modes and family identity. These settings are consumed by the server to enforce access control and by the client to display the family name.

    Authentication Configuration

    Use these variables to control how users access the family tree:

    • NEXT_PUBLIC_REQUIRE_AUTH: Set to 'true' to enable authentication requirements.
    • AUTH_MODE: Determines the authentication strategy. Options are 'all' (allow all family members) or 'specific' (only allow specific names). Defaults to 'specific'.
    • SPECIFIC_NAME: The specific name allowed to access the tree when AUTH_MODE is set to 'specific'.
    • NEXT_PUBLIC_FAMILY_NAME: The base family name (e.g., Wang). Defaults to '姓氏'.

    Public Configuration

    The following variables are exposed to the client-side via getPublicConfig():

    • NEXT_PUBLIC_FAMILY_NAME: Used to display the family name.
    • NEXT_PUBLIC_REQUIRE_AUTH: Used to determine if the UI should show authentication prompts.
    # Example .env file configuration
NEXT_PUBLIC_REQUIRE_AUTH=true
AUTH_MODE=specific
SPECIFIC_NAME=JohnDoe
NEXT_PUBLIC_FAMILY_NAME=Smith

  10. Authenticate requests using Bearer tokens

    main

    When requireAuth is enabled, the server expects a Bearer token in the Authorization header. The token must be a Base64-encoded JSON string containing an exp (expiration) field representing the timestamp when the token becomes invalid. The server validates that the current time is less than the exp value.

    // Example of the JSON structure inside the Base64 token
{
  "exp": 1720000000000
}

  11. Configure project environment variables

    main

    The project uses environment variables for authentication, family naming, and port settings. First, create your local environment file from the template:

    cp .env.local.example .env.local

    Then, edit .env.local to configure the following keys:

    # Whether login authentication is required (true/false)
NEXT_PUBLIC_REQUIRE_AUTH=false

# Authentication mode (all: allow all family members, specific: only allow specific names)
AUTH_MODE=specific
# Specific user login name
SPECIFIC_NAME=白景琦

# Family name configuration (used for website title, description, and footer)
NEXT_PUBLIC_FAMILY_NAME=白

# Application port configuration
PORT=3000

  12. Configure animation and debounce timing via ANIMATION_DELAYS

    main

    The ANIMATION_DELAYS object controls the timing for UI transitions and input debouncing.

    • SCROLL_TO_MATCH: Delay (ms) before scrolling to a matched search result.
    • HIGHLIGHT_DURATION: How long (ms) a search match remains highlighted.
    • SEARCH_DEBOUNCE: The debounce delay (ms) for the search input to prevent excessive processing.
    export const ANIMATION_DELAYS = {
  SCROLL_TO_MATCH: 100,
  HIGHLIGHT_DURATION: 2000,
  SEARCH_DEBOUNCE: 300,
} as const;