Astrsk AI Storytelling and Roleplaying Platform

The InitializationScreen is a transient UI component that appears only if the app initialization process takes longer than 1 second. It operates in two distinct modes depending on the success of the initialization steps:

Normal Progress (Simple Mode)

Designed for regular users to avoid information overload. It groups the 18 technical steps into 3 high-level categories:

1. Database Setup
2. Services Initialization
3. Data Loading

Group states are indicated by:

• pending: Gray
• running: Blue Loader2 (rotating animation)
• success: Green CheckCircle2

Error Mode (Detailed Mode)

Triggered when a step fails. The UI shifts to provide debugging information:

• The logo animation stops.
• The progress bar is maintained.
• Failed step details are displayed, including the step number, label, error message (in a red box), and duration.
• Action buttons allow the user to "Retry Initialization" (page refresh) or "Copy Error Details" (to clipboard).

To avoid scattered and error-prone cache keys, the project uses a Hierarchical Query Factory. This pattern centralizes all query keys into a single, type-safe object and provides corresponding queryOptions for fetching data.

This approach ensures:

• Single source of truth: Keys are defined once.
• Type-safety: TypeScript autocomplete for keys and query functions.
• Hierarchical structure: Keys follow a predictable path (e.g., flows → detail → nodes), allowing for granular or broad cache invalidation.
• No typos: Prevents bugs caused by manual string/array key entry in components.

// app/queries/flow/query-factory.ts
export const flowKeys = {
  all: ['flows'] as const,
  lists: () => [...flowKeys.all, 'list'] as const,
  list: (filters?: FlowFilters) => [...flowKeys.lists(), { filters }] as const,
  details: () => [...flowKeys.all, 'detail'] as const,
  detail: (id: string) => [...flowKeys.details(), id] as const,
  nodes: (flowId: string) => [...flowKeys.detail(flowId), 'nodes'] as const,
  node: (flowId: string, nodeId: string) => [...flowKeys.nodes(flowId), nodeId] as const,
}

export const flowQueries = {
  detail: (id: string) => queryOptions({
    queryKey: flowKeys.detail(id),
    queryFn: async () => {
      const flow = await FlowService.getById(id);
      if (!flow) throw new Error('Flow not found');
      return flow;
    },
    staleTime: 1000 * 10,
  }),

  nodes: (flowId: string) => queryOptions({
    queryKey: flowKeys.nodes(flowId),
    queryFn: async () => FlowService.getNodes(flowId),
    staleTime: 1000 * 5,
  }),
}

Create Entity

Use onSuccess in a mutation to optimistically update lists and detail caches.

Delete Entity

Use onSuccess to removeQueries for the specific item and update parent lists by filtering the existing cache.

Dependent Queries

Use the enabled option to ensure a query only runs once the data from a previous query is available.

Parallel Queries

Use the useQueries hook to fetch multiple independent datasets simultaneously.

// Dependent Queries
const FlowNodes = ({ flowId }: { flowId: string }) => {
  const { data: flow } = useQuery(flowQueries.detail(flowId));

  const { data: nodes } = useQuery({
    ...flowQueries.nodes(flowId),
    enabled: !!flow, // ⭐ Dependent query
  });

  return <div>{nodes?.length} nodes</div>;
};

// Parallel Queries
const FlowDashboard = ({ flowId }: { flowId: string }) => {
  const queries = useQueries({
    queries: [
      flowQueries.detail(flowId),
      flowQueries.nodes(flowId),
      flowQueries.metadata(flowId),
    ],
  });
  // ...
};

The LegacyCharacterRecovery service is designed to recover character and scenario data when migrations from old database schemas to new ones fail. It detects data in deprecated tables (character_cards, plot_cards, cards) and migrates it to the new tables (characters, scenarios).

Safety and Behavior

• Idempotent: Safe to run multiple times.
• Non-destructive: It never deletes old tables.
• Conflict handling: Uses ON CONFLICT DO NOTHING to prevent duplicate entries.

When to use

• Use if users report missing characters in their library or sessions after an upgrade.
• Use if migration logs show errors related to the character_cards table.
• Do not use if the migration completed successfully (old tables will have been dropped) or if the user simply needs to adjust search filters.

import { LegacyCharacterRecovery } from "@/app/recovery-services";

const recovery = new LegacyCharacterRecovery();

// Check status
const report = await recovery.checkLegacyData();

if (report.canRecover) {
  // Recover all
  await recovery.recoverAll();
}

The astrsk PWA uses a sequential, three-tier initialization process on startup to ensure the database is ready, services are linked, and data is loaded into memory. The tiers are organized by their execution frequency and persistence:

1. Tier 1: Database Migration (One-Time)

   • Purpose: Creates table structures in the PGlite database.
   • Persistence: Persisted in IndexedDB.
   • Execution: Runs only on the first initialization or when the database is missing (checked via isDatabaseInitialized()). If the database is already initialized, migration steps are marked as instant success.

2. Tier 2: Services Initialization (Every Time)

   • Purpose: Handles dependency injection and linking repositories/functions.
   • Persistence: In-memory only (not persisted).
   • Execution: Runs on every app startup. This is necessary because service references (e.g., FlowService.init(AgentService.agentRepo, ...)) are in-memory and do not persist across page reloads.

3. Tier 3: Stores Initialization (Every Time)

   • Purpose: Loads data from the database into in-memory caches.
   • Persistence: In-memory only (not persisted).
   • Execution: Runs on every app startup to repopulate memory caches (e.g., loading API connections, backgrounds, or sessions into the app state).

main.tsx (Orchestration)
  ├── 1. Database Migration (ONE-TIME)
  │   └── migrate() - Runs only on first initialization or when DB is missing
  |
  ├── 2. Services Initialization (EVERY TIME)
  │   └── initServices() - Runs on every app startup (in-memory dependency injection)
  |
  └── 3. Stores Initialization (EVERY TIME)
      └── initStores() - Runs on every app startup (loads data from DB into memory)