# Camp Commons kit

**v0.1.1 · October 30, 2026**

A local camp operations prototype with a fictional camp ready to explore. It connects schedules, ranked electives, rosters, cabins, facilities, vehicles, attendance, meal headcounts and source-linked camp notes. The interface was developed with Kimi and refined through native review and testing.

Copyright © 2026 NTG Consulting LLC. Original project materials are MIT licensed, see [LICENSE](LICENSE). Third-party components retain their own licenses, see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

## What you can try

- Generate a group activity schedule, inspect the proposed assignments, and apply it. Existing locked assignments stay in place.
- Allocate ranked electives with capacity and eligibility checks; inspect campers who could not be placed.
- Move calendar assignments and receive a server-side explanation when a move breaks a rule.
- Edit campers, staff, cabins, groups, facilities, activities, time periods and vehicles.
- Preview and import camper CSV files, export the roster, and inspect revision history.
- Record attendance and trips, view meal headcounts, and keep notes with a source, owner and review date.

The fictional sample has 72 campers, 12 staff, six groups and eight activities. It starts with 24 group sessions on Monday, July 5, 2027. Generate the five-day week to create the remaining schedule. Google OR-Tools supplies the optimizer. This app does not connect to an LLM or require an AI provider key.

## Requirements

The release was tested on Apple Silicon macOS with **Python 3.14.3, Node.js 24.14.0 and npm 11.9.0**. Python 3.14 and Node 24 are the tested runtime families. Windows, Linux, Intel Macs and other runtime versions were not tested for this release.

Install [Python](https://www.python.org/downloads/) and [Node.js](https://nodejs.org/en/download) if needed. Internet access is required for the first installation because dependencies are downloaded. The kit does not include a Python environment, npm packages or a prebuilt frontend.

In Terminal, check:

```sh
python3 --version
node --version
npm --version
```

## Install and open

1. Unzip the download. Keep the resulting `CampCommonsKit` folder together in a location where you can write files.
2. Open Terminal, type `cd ` with a trailing space, drag the `CampCommonsKit` folder into the window, and press Return.
3. Install and build:

```sh
bash setup.sh
```

4. Start the app:

```sh
bash run.sh
```

5. Open **http://127.0.0.1:8765** in your browser. Keep Terminal running while you use the app.

Setup creates a local Python environment, installs pinned packages, builds the frontend, migrates a new SQLite database and seeds fictional data. It only seeds an empty workspace; rerunning setup or the launcher does not reset existing records.

**Quit:** press Control-C in the server's Terminal window. Closing the browser alone does not stop the server.

**Restart:** return to this folder and run `bash run.sh`. Your local data remains. After setup, `Start Camp Commons.command` is an optional Mac double-click launcher. If macOS will not open it, use the Terminal commands above.

**Use another port:**

```sh
CAMP_PORT=8775 bash run.sh
```

Then open http://127.0.0.1:8775. The server binds to loopback only. Do not expose this development server to a network or treat it as a hosted camp service.

## First walkthrough

1. Inspect the dashboard's sample Monday and the roster.
2. In the planner, generate five days starting July 5, 2027. Review the proposal, then apply it. Preview alone does not change the schedule.
3. Open a camper and change their activity preferences. Open electives for an elective period, preview allocation, inspect preference outcomes, then apply.
4. Changing preferences later updates current ranks while preserving existing placements and their history. Generate a new proposal to move campers.
5. Explore operations, attendance and meal counts. Read the stated baseline before interpreting a headcount.
6. Add a knowledge note with a source and review date. Notes are reference material; their prose does not become an enforced scheduling rule.

## Contents

| Path | Purpose |
|---|---|
| `README.md` | Installation, use, backup, limits and troubleshooting |
| `COPYRIGHT.txt` | Copyright notice for original materials |
| `THIRD_PARTY_NOTICES.md` | Direct dependencies, verified licenses and upstream links |
| `REUSE.md`, `DEPENDENCIES.json` | Prior-art decisions and dependency inventory |
| `REVIEW_SUMMARY.md`, `VERIFICATION.md` | Sanitized review findings and release checks |
| `backend/` | Django application, models, migrations, solver and 69 tests |
| `frontend/` | React application, package lock and 12 unit tests |
| `requirements.txt`, `requirements.lock.txt` | Direct and complete pinned Python dependencies |
| `setup.sh`, `run.sh`, `Start Camp Commons.command` | Install and local launch scripts |
| `qa/audit_workspace.py`, `qa/test_audit.py` | Independent read-only data audit and 16 fixture tests |
| `KIT_FILES.txt`, `tools/build_kit.py` | Explicit source-package allowlist and reproducible ZIP builder |
| `SHA256SUMS` | Checksums of every other file delivered in this archive |

No saved database, credentials, provider request logs, local review logs, installed dependencies or generated frontend bundle is included.

## Local data and backups

The default database is `backend/db.sqlite3`. The app also creates `backend/.local-secret` to sign short-lived proposals. Both stay on your computer. Keep the database private if you enter your own information; this release is intended for fictional-data evaluation.

To back up, stop the server first and copy the entire kit folder to a private backup location. At minimum preserve `backend/db.sqlite3` and `backend/.local-secret` with the matching source release. To restore, stop the server, replace those two files with your backup, and restart. Reinstall dependencies with `bash setup.sh` if restoring on a different computer or into a fresh environment. Never overwrite your only good backup.

The workspace JSON export is a readable data snapshot. It is not a full database/history backup, and there is no workspace JSON restore interface. Camper CSV import is the supported roster import path.

For a fresh fictional camp, unzip a separate copy and run setup there. Use a different port if another copy is running. Starting again in the same folder preserves its existing data.

## Limits to understand

This is a local, single-operator prototype. It has no production user authorization or tenant isolation. It does not implement parent registration, payments, messaging, CampMinder integration or an AI assistant.

Scheduling checks include capacities, qualifications, availability, locks and repeat limits. They do not establish staffing ratios, certification validity, medical or allergy safety, emergency readiness or overall operational safety. The seeded model assigns activity specialists, not every adult needed to supervise a camp.

Trips have conflict checks but are not a road-routing or transport-management system. An attendance record does not automatically remove a camper from their activity assignments. A camper may need elective preferences entered explicitly. Camp-end dates do not constrain every scheduling action. Changing a hard rule can require repairing existing assignments; this version does not provide a guided exception-repair queue.

Meal counts use the application's stated roster/attendance baseline and overlapping dietary categories. They are not meal-specific catering instructions. Knowledge notes retain sources and revisions but are not linked automatically to the records or rules they describe.

The tests use the fictional six-group camp and smaller negative fixtures. They do not establish performance for a large production camp. The JavaScript build reports a bundle-size advisory; the app still builds and serves. See [VERIFICATION.md](VERIFICATION.md) for the precise checks and boundaries.

## Troubleshooting

| Symptom | Next step |
|---|---|
| `python3`, `node` or `npm` is missing | Install the tested runtime family above, open a new Terminal and check its version. |
| Dependency installation fails | Check internet access and runtime versions. Rerun `bash setup.sh` from the kit folder. Keep the error text if it persists. |
| Launcher says to run setup | Run `bash setup.sh`; both `.venv/bin/python` and `frontend/dist/index.html` must exist. |
| Port already in use | Stop the other instance or use `CAMP_PORT=8775 bash run.sh` and its matching URL. |
| Double-click launcher is blocked or not executable | Use `bash run.sh` in Terminal. For an executable-bit issue, `chmod +x "Start Camp Commons.command"` restores it. |
| Proposal is expired or stale | Generate a new preview against the current records, then review and apply it. |
| An edit or schedule is rejected | Read its constraint explanation; check capacities, qualifications, availability and existing assignments before retrying. |
| Layout looks wrong after resizing | Refresh the browser at the intended window size. |

## Recheck this release

Before installation, verify the archive's file checksums from the extracted folder:

```sh
shasum -a 256 -c SHA256SUMS
```

After setup:

```sh
.venv/bin/python backend/manage.py test camp
python3 -m unittest discover -s qa -p 'test_*.py'
npm test --prefix frontend
npm run build --prefix frontend
.venv/bin/python backend/manage.py check
.venv/bin/python backend/manage.py makemigrations --check --dry-run
```

While the server is running, check persisted assignments independently:

```sh
python3 qa/audit_workspace.py --url http://127.0.0.1:8765
```

The source packager is optional. `python3 tools/build_kit.py` recreates `dist/CampCommonsKit.zip` from the exact allowlist, with a separate ZIP checksum and file manifest. Files created by installation are excluded.