S6 Schools Easy Start Guide

This guide gets a new evaluator, school owner, or pilot administrator from a fresh local checkout to a useful S6 Schools demo run.

For a newly provisioned school administrator, follow the screen-by-screen Visual School Setup Guide after signing in. It uses the same sequence as the readiness hub and links directly to each live workspace.

For production deployment, use docs/VPS_DEPLOYMENT.md instead. This file is for local demo, training, and pilot preparation.

1. What You Need

• Windows, macOS, or Linux with Node.js and npm.
• Docker Desktop with virtualization enabled.
• PostgreSQL provided by docker compose.
• This repository checked out locally.

The app uses:

• Next.js frontend on http://localhost:3000
• NestJS API on http://localhost:4000/api
• PostgreSQL on localhost:5432

2. Start The App

From the repo root:

docker compose up -d postgres
npm install
npm run db:generate
npm run db:push
npm run db:seed
npm run dev

Open:

• App: http://localhost:3000/login
• API health: http://localhost:4000/api/health
• API readiness: http://localhost:4000/api/health/ready

3. Demo Accounts

All local seeded accounts use this password:

edupilot123

4. First 15-Minute Walkthrough

Step 1: Sign in as school admin

1. Go to http://localhost:3000/login.
2. Sign in with admin@edupilot.test and edupilot123.
3. Confirm the Dashboard button remains visible in the app shell.

Step 2: Check school setup

Go to /app/onboarding.

Use the School Setup hub to:

• Review required setup progress.
• Follow CTAs into settings, records, login cards, import/export, and data quality.
• Run a data quality scan.
• Skip optional recommended steps when they are not needed for a demo.
• Mark setup complete only after required checks pass.

If the curriculum foundation option is available, open /app/onboarding/curriculum after setting the school profile. Choose the correct starter template or explicitly continue with Blank/custom before manually creating the academic structure.

Then open /app/settings.

Confirm or update:

• School name and contact details.
• Branding colours and logo.
• Academic defaults.
• Report settings.
• Uploaded school files.

Step 3: Check records

Go to /app/records.

Use the tabs to review:

• Learners.
• Guardians.
• Staff.
• Classes.
• Subjects.
• Login cards.
• CSV import/export.

Try these quick actions:

1. Create a learner.
2. Create or edit a guardian.
3. Link the guardian to the learner.
4. Generate login cards.
5. Reissue staff login credentials.

Step 4: Send a communication

Go to /app/communications.

Try:

1. Create an announcement.
2. Publish it.
3. Open SMS Campaigns.
4. Draft a campaign to a safe demo audience.
5. Send in dry-run mode unless real SMSMessenger credentials are configured.

Step 5: Run daily attendance

Go to /app/attendance.

Try:

1. Select a class and date.
2. Create a register.
3. Mark all present.
4. Mark one learner absent or late.
5. Submit the register.
6. Check that absence notifications and summaries update.

Step 6: Run the teacher workflow

Sign out and sign in as teacher@edupilot.test.

Try:

1. Open /app/learning.
2. Create or update homework.
3. Review learner submissions.
4. Mark a submission and add feedback.
5. Open /app/question-bank.
6. Create or review a question.
7. Open /app/quizzes.
8. Create or update a quiz.
9. Open /app/reports.
10. Capture marks.

Step 7: Run the learner workflow

Sign in as learner@edupilot.test.

Try:

1. View assigned homework.
2. Submit homework.
3. Attempt a quiz.
4. Review results and feedback.
5. Check timetable and resources.

Step 8: Run the parent workflow

Sign in as parent@edupilot.test.

Try:

1. View linked child dashboard data.
2. Open homework.
3. Review gradebook entries.
4. View reports.
5. Submit an absence note.
6. View finance statements for linked accounts.

Step 9: Check leadership views

Sign in as principal@edupilot.test or hod@edupilot.test.

Try:

1. Review HOD or principal dashboard.
2. Open /app/insights.
3. Generate or inspect academic risk snapshots.
4. Create an intervention plan.
5. Open /app/data-quality.
6. Run a data quality scan.

5. Key App Areas

6. Live Provider Safety

By default, the demo is safe:

• SMS sends stay dry-run unless SMSMessenger credentials are configured.
• Email invitations use local dry-run unless SMTP is configured.
• WhatsApp is disabled or dry-run only.
• Payments use the dummy provider unless a real provider is implemented and configured.
• Demo seed is blocked in production unless explicitly allowed.

Do not add production secrets to the repository.

7. Common Checks

Run these before a demo or handover:

npm run lint
npm run test:api
npm run build
npm run test:e2e
npm run smoke

npm run test:api and npm run test:e2e reset/reseed the local test database. Do not run them against a real school database.

8. Troubleshooting

Postgres is not reachable

Run:

docker compose up -d postgres

Then rerun:

npm run db:push
npm run db:seed

Login fails

Check:

• You are using a seeded email from this guide.
• The password is edupilot123.
• The API is running on http://localhost:4000/api.
• The database was seeded.

App opens but pages are empty

Check API readiness:

npm run smoke

Or open:

http://localhost:4000/api/health/ready

SMS does not send live

That is expected unless SMSMessenger credentials are configured. In dry-run mode, delivery records are still created for testing.

Payment checkout is a demo URL

That is expected. Live payment providers are future/provider-gated and must not be represented as active.

9. What To Read Next

• Visual school setup: /manual/school-setup
• Full manual: docs/USER_MANUAL.md
• Feature map: FEATURES.md
• Product spec: PRODUCT.md
• Known limitations: docs/KNOWN_LIMITATIONS.md
• VPS deployment: docs/VPS_DEPLOYMENT.md
• Backup and restore: docs/BACKUP_RESTORE.md
• Security: SECURITY.md and docs/SECURITY_PRODUCTION.md