Pal

A gamified learning companion that connects to platforms like Pika. Students earn a living pet and an evolving world just by doing their schoolwork — submitting assignments, maintaining streaks, hitting milestones. The more they engage, the more their world grows.

The experience

A student submits an assignment in Pika. Their pet bounces with excitement. A plant sprouts in their world. After a month of consistent work, the sun appears. After a semester, their world looks completely different from the one they started with — built entirely from their own effort.

They can see their achievements and companion as native Pal-powered surfaces inside Pika, or visit Pal directly. Either way, it is their world, shaped by their work.

What Pal owns

1. Pet state — mood, animation, energy (reacts to events in real time)
2. World state — an environment that grows through time, effort, and milestones
3. The rules — what learning signals cause what changes

What it does NOT own

• Student identity or authentication (that's Pika's)
• Grades, scores, or raw learning data
• Classroom management
• The current assignment catalog, deadlines, deletion/archive state, or assignment-specific incomplete status

Privacy is a first-class constraint. Pal receives only pseudonymous IDs and low-risk signals — never names, grades, or student content.

How it connects to Pika (and other platforms)

The current developer panel exercises assignment.completed and daily_checkin.created; the prototype ingest API also retains legacy resource and calendar allow-list entries. The target initial Pika adapter will automatically send six normalized, privacy-safe facts:

• platform.session.started
• classroom.joined
• daily_log_week.configured
• daily_log.completed
• learning_item.viewed
• learning_item.completed

Pal derives streaks, achievements, and rewards from those signals, then updates the student's pet and world. Pika renders the result with the React surfaces from @codepet/pal-widget; non-React integrations may use a future chrome-free embed route.

The initial integration rewards behavior that actually occurred; it does not mirror Pika's assignment system. Showing every untouched or incomplete assignment would require a separate, later Pika-owned academic projection with reconciliation.

Any learning platform can integrate this way. Pika is the first.

The dev sandbox

Developers working on Pal use a built-in host sandbox to exercise the same public @codepet/pal-widget surfaces that Pika consumes. A collapsible control panel starts with explicit fixture scenarios and evolves into a real-pipeline event injector; it never ships in the learner widget.

Team

Design discussions, proposals, and feedback happen in Discord. Bring an idea to Discord first — once it's agreed on, update the relevant doc in this repo. The docs here are the source of truth for decisions already made, not a place to debate them.

Quick links

• Architecture overview
• Data model
• API contracts
• Rule engine
• Integration guide
• Pika signal adapter and achievement pipeline
• Pika–Pal achievement pilot plan
• Widget integration
• Widget release
• Development workflow
• Roadmap

Repo structure

apps/
  web/          # Student viewer, dev sandbox, and all API routes (Next.js)
    public/assets/   # Static game art — pets/, world/, badges/
packages/
  engine/       # Rule engine (pure functions, no DB)
  db/           # Drizzle schema + migrations
  contract/     # Versioned integration event contracts
  widget/       # Portable React achievement, companion, and reward surfaces
docs/           # Living architecture documents (start here)

The operator and teacher console remains planned work; it will live under apps/admin/ when that milestone begins.

Next.js serves both the UI and the API — there is no separate API server. See Tech stack.

Getting started

1. Read docs/architecture.md — understand the system before writing any code
2. Find your domain in docs/dev-workflow.md — each developer owns a vertical slice
3. Read your domain's doc — linked from the workflow doc
4. Pick up Milestone 1 (M1) tasks for your domain — the first goal is a working dev sandbox with event ingest and a visible pet reaction

This project uses pnpm. Do not use npm install — it will create conflicts.

npm install -g pnpm   # install pnpm if you don't have it
pnpm install          # install all dependencies
pnpm dev              # start the dev server

Then open http://localhost:3000/sandbox to see the dev sandbox.