Inkverse Setup Instructions

Inkverse is a fun comic reading app built using Typescript, React, React Native, Node.js, and GraphQL.

Table of Contents

• Monorepo Structure
• Architecture
• Quick Setup (Website)
• Quick Setup (React Native)
• Full Local Setup
• Helpful Commands
• Additional Docs

Monorepo Structure

website/          # React web frontend
react-native/     # React Native mobile app
graphql-server/   # Node.js GraphQL backend
worker/           # To run background jobs
cloud/            # Cloudflare edge services
packages/         # Internal packages
  ├── shared-client/   # Frontend shared utilities
  ├── shared-server/   # Backend shared utilities
  └── public/         # Shared constants and types

Architecture

---

Quick Setup (Website)

Setup the website by pointing it to Inkverse's production API for quick setup and without needing to setup a local server.

Prerequisites

• Node.js >= 24
• Yarn package manager

Steps

1. Install Dependencies

# Install all project dependencies
yarn install

2. Configure Custom Localhost

We use inkverse.test instead of localhost to avoid cookie conflicts between projects. Add to your hosts file (sudo vim /etc/hosts on Mac/Linux):

127.0.0.1               localhost
127.0.0.1               inkverse.test

3. Configure for Production API

In website/config.ts, change:

// Change this line:
export const config = developmentConfig;

// To this:
export const config = developmentConfigButProductionData;

This will get the website to use Inkverse's production API.

4. Build and Watch for changes in internal packages

# Start watching internal packages
yarn watch:internal-packages

5. Start the Website

cd website
yarn dev

🎉 Success! Visit inkverse.test:8082 to see the app.

6. Authentication Note

⚠️ Note: Google/Apple/Email signup don't work in local development due to CORS restrictions. Use the React Native app for production account login.

---

Quick Setup (React Native)

Setup the iOS/Android apps by pointing it to Inkverse's production API for quick setup and without needing to setup a local server.

Prerequisites

• Node.js >= 20
• Yarn package manager

Steps

1. Install Dependencies

yarn install

2. Configure Custom Localhost

We use inkverse.test instead of localhost to avoid cookie conflicts between projects. Add to your hosts file (sudo vim /etc/hosts on Mac/Linux):

127.0.0.1               localhost
127.0.0.1               inkverse.test

3. Configure for Production API

In react-native/config.ts, change:

// Change this line:
export const config = developmentConfig;

// To this:
export const config = developmentConfigButProductionData;

This will get the React Native app to use Inkverse's production API.

4. Build and Watch for changes in internal packages

# Start watching internal packages
yarn watch:internal-packages

5. Start the App

cd react-native
yarn dev

• Press i for iOS Simulator
• Press a for Android Emulator

6. Login with Production Account

⚠️ Note: Google/Apple signup don't work in local development. Use email login:

1. Go to Profile → Sign Up → Continue with email
2. Check your email for the login link
3. When you return to the app, paste the login link in the text input

---

Full Local Setup

Complete Setup: For building new features or fixing complex bugs, you'll need to setup the backend as well as the website and mobile apps. Follow the steps below to setup the backend locally.

Prerequisites

• Node.js >= 20
• Yarn package manager
• Docker Desktop (Download here)

Steps

1. Environment Configuration

Copy the environment template:

cp packages/shared-server/.env.example packages/shared-server/.env

2. Database Setup (PostgreSQL)

Create and start PostgreSQL container:

# Replace USERNAME, PASSWORD, and DB-NAME with your preferred values
docker run --name inkverse-postgres \
  -e POSTGRES_USER=USERNAME \
  -e POSTGRES_PASSWORD=PASSWORD \
  -e POSTGRES_DB=DB-NAME \
  -d \
  -v ~/docker-vms/inkverse-postgresdata:/var/lib/postgresql \
  -p "5432:5432" \
  postgres:18.4

Update .env file:

DATABASE_USERNAME=USERNAME
DATABASE_PASSWORD=PASSWORD
DATABASE_NAME=DB-NAME
DATABASE_ENDPOINT=localhost
DATABASE_PORT=5432

3. Message Queue Setup (AWS SQS Local)

docker run -d --name inkverse-queues -p 4102:4100 admiralpiett/goaws

4. JWT Key Generation

Generate RSA key pair for JWT tokens:

# Generate private key
ssh-keygen -t rsa -b 4096 -m PEM -f jwt.key

# Generate public key
openssl rsa -in jwt.key -pubout -outform PEM -out jwt.key.pub

Update .env file with the keys (remove newlines, replace with \n):

PUBLIC_JWT=your_public_key_here
PRIVATE_JWT=your_private_key_here

Clean up key files:

rm jwt.key jwt.key.pub

5. Install Dependencies

yarn install

6. Database Migration

yarn run migrate

7. Configure Hosts

Add to your hosts file (sudo vim /etc/hosts):

127.0.0.1               localhost
127.0.0.1               inkverse.test
127.0.0.1               us-east-1.goaws.com # For AWS SQS Local

8. Start Internal Packages

# Keep this running in a separate terminal
yarn watch:internal-packages

9. Start the Backend

cd graphql-server
yarn run dev

🎉 Success! Inkverse Server is running on inkverse.test:3010.

10. Add comics to your local database

Yay! You have Inkverse running locally, but you don't have any comics in your database to display! Let's fix that.

What we'll do:

1. Download a list of comics from Taddy's Webcomics API
2. Set up a queue to process the comic data
3. Fetch detailed information for each comic and import it into your database

Step 1: Download comics list

Download the full comics list from Taddy's Webcomics API and rename it to comicseries.txt. Place it in the worker/input directory.

Step 2: Create a queue to handle the responses from Taddy's API

cd worker
yarn run create-new-queue INKVERSE_HIGH_PRIORITY

Step 3: Get detailed information about each comic and its episodes

Get your Taddy API User ID and API Key for free by signing up here. Add them to your .env file in packages/shared-server:

TADDY_USER_ID=your_user_id
TADDY_API_KEY=your_api_key
TADDY_WEBHOOK_SECRET=xyz
TADDY_WEBHOOK_ENDPOINT_URL=http://inkverse.test:3010/api/worker/process-taddy-webhook

You will also need to add TADDY_WEBHOOK_SECRET and TADDY_WEBHOOK_ENDPOINT_URL to your .env file in worker/.env. You can use the same values as above. (You can use any value for WEBHOOK_SECRET, it just has to be the same for both files)

TADDY_WEBHOOK_SECRET=xyz
TADDY_WEBHOOK_ENDPOINT_URL=http://inkverse.test:3010/api/worker/process-taddy-webhook

Then run the following command to download detailed information about each comic and its episodes:

cd worker 
yarn run import-all-comics

Step 4: Add the comics to your local database

Finally, run the following command process every message in the INKVERSE_HIGH_PRIORITY queue (each message contains details about a comic and its episodes) and we will add these comics and episodes to your local database.

cd worker 
yarn run receive-messages INKVERSE_HIGH_PRIORITY

---

Helpful Commands

Docker Management

# Start all containers
docker start inkverse-postgres && docker start inkverse-queues

# Stop all containers
docker stop inkverse-postgres && docker stop inkverse-queues

# View running containers
docker ps -a

Development Commands

# Watch and rebuild internal packages (you need to always have this running in the background to check for changes with  your internal packages)
yarn watch:internal-packages

# Start backend server
cd graphql-server && yarn run dev

# Start website
cd website && yarn run dev

# Start React Native (Expo)
cd react-native && yarn dev

# Start React Native (Development Build)
cd react-native && yarn run ios     # iOS
cd react-native && yarn run android # Android

Database Commands

# Run migrations
yarn run migrate

# Rollback last migration
yarn run migrate:rollback

GraphQL Commands

# Generate types after schema changes
yarn run graphql-codegen

---

Additional Docs

Document	Description
CLAUDE.md	Claude AI instructions for working with the project
Architecture	High-level overview of the application
Docs Folder	Complete project documentation