Installation Guide

Welcome to the Writers Factory Alpha. In this course, you’ll be both a writer and a developer—running the app locally, tracking the codebase, and contributing improvements.

You Are Both Developer and Writer

As a Writer, you’ll use Writers Factory to develop your novel—from Story Bible through Voice Calibration to scene drafting.

As a Developer, you’ll:

• Run the app locally using terminal commands
• Track the codebase in an IDE (VS Code recommended)
• Report bugs when you find them
• Submit Pull Requests for improvements you want to make

This dual role means you’ll understand the tool deeply and help make it better for future writers.

Step 0: Get Repository Access

The Writers Factory code is in a private GitHub repository. To get access:

1. Create a GitHub account (if you don’t have one): github.com
2. Send your GitHub username to your instructor
3. Wait for the invitation email from GitHub
4. Accept the invitation to join the repository

Once you have access, you can proceed with installation.

Prerequisites

Install these tools before class to save time:

Install Rust

macOS/Linux:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Windows: Download and run rustup-init.exe from rustup.rs

Important: Restart your terminal after installing Rust, then verify: rustc --version

Step 1: Clone the Repository

Once you have repository access:

git clone https://github.com/gcharris/writers-factory-app.git
cd writers-factory-app

Open the folder in VS Code:

code .

Step 2: Start the Backend (Terminal 1)

Open your terminal (Terminal on Mac, PowerShell on Windows).

macOS/Linux

cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn api:app --reload --port 8000

Windows

cd backend
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
uvicorn api:app --reload --port 8000

If activation fails on Windows with a policy error:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Success: You see “Application startup complete” on http://127.0.0.1:8000

Keep this terminal OPEN. The backend must stay running.

Step 3: Start the Desktop App (Terminal 2)

Open a new terminal window (keep Terminal 1 running).

cd frontend
npm install
npm run tauri dev

First run: Rust compiles the desktop app (~2-5 minutes). After that, it starts in ~10 seconds.

Success: The Writers Factory desktop app launches automatically.

Daily Workflow

Each time you want to use Writers Factory:

Terminal 1 (Backend):

cd writers-factory-app/backend
source .venv/bin/activate   # Mac/Linux
# .venv\Scripts\Activate.ps1  # Windows
uvicorn api:app --reload --port 8000

Terminal 2 (Frontend):

cd writers-factory-app/frontend
npm run tauri dev

Contributing: Bugs and Improvements

When you find a bug or have an improvement:

Report an Issue

1. Go to the GitHub repository
2. Click the Issues tab
3. Click New Issue
4. Describe the problem clearly with steps to reproduce

Submit a Fix (Pull Request)

git checkout -b fix/short-description
# Make your changes
git add .
git commit -m "Fix: description of what you fixed"
git push origin fix/short-description

Then open a Pull Request on GitHub.

Troubleshooting

“Cannot connect to backend” errors

• Make sure Terminal 1 is running with uvicorn
• Check for error messages in Terminal 1

App won’t compile (Rust errors)

• Verify Rust is installed: rustc --version
• Try: cd frontend/src-tauri && cargo clean then restart

Python errors

• Check you’re in the virtual environment (prompt shows .venv)
• Try: pip install -r requirements.txt again

“Port already in use”

Another instance is running. Close it, or:

# Mac/Linux
lsof -i :8000 | grep LISTEN
kill -9 [PID]

Getting Updates

When your instructor pushes updates:

cd writers-factory-app
git pull origin master

Then restart both terminals.

Next Step

Once the app is running, proceed to First Launch & Setup to activate your course subscription.