Getting Started with Seed & Source

Getting Started with Seed & Source

Audience: Beginners, first-time users, and teams evaluating Seed & Source Goal: Go from zero to a deployed project in under 30 minutes Estimated time: 25 to 30 minutes (landing page) or 30 to 45 minutes (full-stack)

---

Table of Contents

1. Welcome
2. Prerequisites
3. Install the CLI
4. Authenticate
5. Quickstart: Landing Page (static-landing)
6. Production Build (landing page)
7. Deploy Options (Vercel, Netlify, S3)
8. Full-Stack Quickstart (python-saas + react-client)
   • 8.8 Sandbox Mode — Full Stack in One Command
9. Template Structure Overview
10. Feature Enable Example
11. Testing
12. Command Cheat Sheet
13. Troubleshooting
14. Next Steps
15. Beginner Tips
16. FAQ
17. Appendix: Glossary

---

1. Welcome

Seed & Source is a curated set of production-ready templates plus a CLI called sscli. The templates are designed to be deployed quickly while still using clean, maintainable architecture. This guide walks you through a simple landing page deployment first, then shows how to start a full-stack app.

If you are completely new, start with the landing page path. It is the fastest way to get a working deployment and learn the workflow. Then come back for the full-stack section once you are comfortable.

If you are working in a team, consider pairing for the first run. One person can read the steps while the other runs commands. This makes the first pass smoother and helps everyone share the same mental model of the workflow.

What you will build in this guide

• A static landing page that you can deploy in under 30 minutes.
• A basic full-stack foundation you can extend with features later.

Time boxes (realistic for beginners)

• 5 to 10 minutes: Install and authenticate the CLI.
• 10 to 15 minutes: Create and customize a landing page.
• 5 to 10 minutes: Production build and deploy the landing page.
• 10 to 15 minutes: Scaffold the full-stack backend + frontend.

If you are short on time, complete sections 1 through 7 and stop. You will still have a live deployment and a strong sense of the workflow.

---

2. Prerequisites

Required

• Docker Desktop (macOS/Windows) or Docker Engine (Linux)
• Python 3.11+
• Git
• A terminal or command line

Optional (recommended)

• Node.js 18+ (for React Client development)
• VS Code (editor)
• Ruby 3.2+ (for Rails API development)

Why these are needed

• Docker provides a consistent build and deploy path across all templates.
• Python is required for the sscli installer and runtime.
• Git helps you track changes and deploy from a clean repo.
• Node.js is required if you plan to run the React client locally.

Install notes for beginners

• If you are on macOS, install Python from python.org or via Homebrew.
• If you are on Windows, install Python from python.org and ensure the “Add python.exe to PATH” option is checked.
• Docker Desktop is the simplest path for Mac and Windows. Linux users can install Docker Engine directly.

Recommended folder layout Keep your projects organized in a single workspace folder, for example:

~/Projects/seed-source/
  my-landing/
  my-saas-api/
  my-saas-web/

Quick check commands

python --version
docker --version
git --version

---

3. Install the CLI

We recommend pipx so the CLI stays isolated from project dependencies, but standard pip works too.

Option A: pipx (recommended)

pipx install sscli

Option B: pip

pip install sscli

Verify installation

sscli --version

Expected output:

sscli version 2.x.x

If the command is not found

• For pipx: run pipx ensurepath and restart your terminal.
• For pip: make sure your Python bin directory is in PATH.

Optional: update to the latest If you already have sscli installed:

pipx upgrade sscli

---

4. Authenticate

You will need an account to access templates and features.

sscli login
sscli whoami

If you are prompted for credentials, follow the on-screen instructions. If you are already logged in, sscli whoami should return your account information.

What authentication unlocks

• Access to the templates available to your account tier.
• Feature modules that can be injected during scaffold.
• Consistent template updates managed by the CLI.

If you are working offline You can still edit existing projects, but you may not be able to scaffold new templates without a license check.

---

5. Quickstart: Landing Page (static-landing)

This is the fastest path to a live deployment. The static-landing template is built with Astro and Tailwind, and it uses a simple blueprint.json for content.

5.1 Create the project

sscli new --template static-landing --name my-landing
cd my-landing

5.2 Explore the structure

Key files and folders you will touch first:

• blueprint.json - content and theme configuration
• src/components/ - reusable sections
• src/pages/ - main page definitions
• tailwind.config.mjs - theme and design tokens

Why the blueprint matters blueprint.json is the fastest way to update your marketing content. You can update headlines, call-to-action buttons, features, and pricing sections without touching component code. For most landing pages, it is the only file you need to edit.

5.3 Start the dev server

npm install
npm run dev

Open http://localhost:4321 in your browser. Make a small change in blueprint.json and confirm it hot-reloads.

5.4 Make a simple change

Open blueprint.json and edit the hero title or subtitle. Save the file and refresh your browser if it does not auto-reload.

Example snippet

{
  "hero": {
    "title": "Ship a clean SaaS in days",
    "subtitle": "A production-ready stack with a calm developer experience"
  }
}

Tip: If you want to change the theme, look for the theme setting in blueprint.json. Many templates include multiple themes like midnight or emerald.

If you want a custom logo

• Drop the file in public/ or assets/.
• Update the blueprint.json reference to match the new file name.

5.5 Customize sections (deeper)

Most sections in the landing page are driven by arrays in blueprint.json. If you see a features grid or pricing cards, you can usually update them without touching component code.

Example: features list

{
  "features": [
    {
      "title": "Deploy in minutes",
      "description": "Use Docker and a clean build pipeline"
    },
    {
      "title": "Stable architecture",
      "description": "Hexagonal structure keeps logic clean"
    }
  ]
}

Example: pricing cards

{
  "pricing": [
    {
      "name": "Starter",
      "price": "$0",
      "features": ["Landing page", "Basic docs"]
    },
    {
      "name": "Pro",
      "price": "$49",
      "features": ["Full stack", "Commerce", "Support"]
    }
  ]
}

If a section is not visible, check whether it is disabled in the blueprint (often a boolean like enabled: false).

---

6. Production Build (landing page)

You can validate a production build locally in two ways: the Astro build output, or the Docker image.

6.1 Astro build

npm run build
npm run preview

Then open http://localhost:4321 to view the production build.

6.2 Docker build

docker build -t my-landing .
docker run -p 8080:80 my-landing

Open http://localhost:8080 to view the optimized static build served by Nginx.

Why run a production build locally

• It lets you verify that your assets are bundled correctly.
• It approximates what a hosting provider will serve.
• It helps catch any missing environment variables early.

What to look for

• Broken images (usually paths in blueprint.json).
• Missing fonts or styles (often due to incorrect static asset paths).
• Layout shifts on mobile (check a small viewport in your browser).

---

7. Deploy Options (Vercel, Netlify, S3)

Pick the option that matches your comfort level. Vercel and Netlify are fastest for beginners. S3 is more flexible for production control.

7.1 Vercel

npm install -g vercel
vercel deploy

When prompted, use the dist/ output folder if the CLI asks for a build directory.

Recommended settings

• Build command: npm run build
• Output directory: dist/

7.2 Netlify

npm install -g netlify-cli
netlify deploy

Netlify may ask for the build command and publish directory. Use:

• Build command: npm run build
• Publish directory: dist/

Tip: If you use Netlify, you can store environment variables in the Netlify UI instead of committing a .env file.

7.3 AWS S3 + CloudFront

S3 is ideal for static hosting with full control over caching and CDN settings.

High-level flow:

1. Build the site locally with npm run build.
2. Create an S3 bucket and enable static website hosting.
3. Upload the dist/ folder.
4. Optionally add CloudFront in front of the bucket for HTTPS and caching.

Common S3 CLI command

aws s3 sync dist/ s3://my-landing-bucket --delete

7.4 Deployment checklist (landing page)

Use this checklist every time you deploy. It helps avoid the most common beginner mistakes.

• Confirm you are on the correct Git branch.
• Run npm run build and check for errors.
• Run npm run preview and confirm the site works locally.
• Commit your changes before deployment.
• Verify the deploy output directory is dist/.
• Confirm the site loads on mobile and desktop.

If you use a hosting provider, store secrets in the provider dashboard, not in your repository.

---

8. Full-Stack Quickstart (python-saas + react-client)

This path creates a backend API and a React frontend. The backend is built on a strict hexagonal architecture to keep business logic isolated from infrastructure.

8.1 Create the backend

sscli new --template python-saas --name my-saas-api
cd my-saas-api

8.2 Create the frontend

sscli new --template react-client --name my-saas-web
cd ../my-saas-web

8.3 Run the backend

If the template includes a RUNBOOK.md, follow it exactly. Common local workflows:

# If the template provides a virtual environment script
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Or run via Docker
docker build -t my-saas-api .
docker run -p 8000:8000 my-saas-api

Backend health check Open http://localhost:8000/docs if the backend uses FastAPI. If you see an API docs page, your backend is running.

8.4 Run the frontend

npm install
npm run dev

Open http://localhost:5173 for the React app (Vite default). If it is running on a different port, the terminal output will show the correct URL.

8.5 Connect frontend to backend

Update the frontend API base URL in its environment file or API client configuration. Typical files:

• src/config/ or src/lib/ for API client setup
• .env or .env.local for host and port

Example environment file

VITE_API_BASE_URL=http://localhost:8000

CORS note If your browser blocks requests, update the backend CORS settings to allow the frontend origin.

8.6 Full-stack data flow (conceptual)

At a high level, the frontend sends requests to the API, the API routes those requests to the domain core, and the core uses adapters to reach external services. This keeps the business logic isolated from delivery and storage concerns.

Typical request path

1. User clicks a button in the React UI.
2. React client sends a request to the API base URL.
3. The API route calls a use case in core/use_cases/.
4. The use case validates data and calls an adapter.
5. The adapter writes to the database or calls a third-party API.
6. The response returns to the frontend and updates the UI.

When you understand this path, you can decide where to add new features and where to place logic.

8.7 Environment variables and secrets

Most templates support .env files for local development. Use them to store API keys and base URLs.

Backend example

DATABASE_URL=postgresql://user:pass@localhost:5432/app
API_KEY=replace_me

Frontend example

VITE_API_BASE_URL=http://localhost:8000
VITE_FEATURE_FLAG=true

Important rules

• Never commit real secrets to Git.
• Use environment variables in CI/CD or your hosting provider dashboard.
• Keep a .env.example file with safe placeholders.

Beginner tip If you are unsure which variables are required, open README.md or RUNBOOK.md in the template. Templates usually list required variables near the top.

8.8 Sandbox Mode — Full Stack in One Command

If you want to skip the manual “install + configure + run” steps above, use the sandbox command. It generates a project and boots it in Docker in one shot:

# Generate a single-service sandbox (landing page)
sscli sandbox up --template static-landing --name my-landing

# Generate and run a full stack (backend + frontend together)
sscli sandbox up --stack python-saas+react-client --name my-app

# With features pre-injected
sscli sandbox up --stack python-saas+react-client --name my-saas

# Specify a custom host port
sscli sandbox up --template python-saas --name my-api --port 9000

What sandbox mode does:

1. Generates the project using sscli generate
2. Copies .env.example → .env
3. Wires VITE_BACKEND_URL automatically for full-stack mode
4. Runs docker compose up --build
5. Waits for all services to become healthy
6. Prints access URLs when ready

Access URLs (defaults):

Service	URL
python-saas backend	http://localhost:8000
react-client admin	http://localhost:5173
static-landing / Astro	http://localhost:4321

Stop the sandbox:

sscli sandbox down --name my-app
# or
docker compose -f ~/.sscli/sandbox/my-app/docker-compose.yml down

When to use sandbox mode: Use it for your first run, demos, or when you want to see a feature working before committing to a full project setup. For ongoing development, use the manual steps in 8.1–8.7 so you have full control over the environment.

---

9. Template Structure Overview

9.1 python-saas (Hexagonal)

src/
├── core/
│   ├── entities/        # Pure domain models (no I/O)
│   └── use_cases/       # Business logic (depends only on entities)
├── infrastructure/      # DB, HTTP, external services
└── ui/                  # FastAPI or Django routes

Rule of thumb: core must never import from infrastructure.

Why this matters Hexagonal architecture keeps your business logic stable while infrastructure changes (databases, message queues, APIs) evolve around it. This makes refactors safer and reduces long-term maintenance costs.

9.2 react-client

src/
├── components/          # UI building blocks
├── hooks/               # Custom hooks (logic)
├── pages/               # Route-level UI
└── lib/                 # API clients and utilities

Rule of thumb: Keep logic in hooks and API clients, not in the components themselves.

Why this matters React components stay smaller and easier to test when state and side effects live in hooks and API clients.

9.3 static-landing

src/
├── components/          # Marketing sections
├── pages/               # Astro routing
└── styles/              # Themes and effects
blueprint.json           # Content and theme settings

Why this matters The blueprint keeps design and content changes accessible to non-developers. You can hand the file to a marketer without touching component code.

9.4 rails-api (Hexagonal, Alba serializer)

app/
├── domain/
│   ├── entities/        # Pure domain models (no I/O)
│   └── ports/           # Repository interfaces
├── infrastructure/
│   └── repositories/    # ActiveRecord implementations
├── use_cases/           # Business logic
├── controllers/         # Rails routes / delivery
└── serializers/         # Alba-based JSON serializers

Status (2026-03-08): Fully validated — 108 RSpec examples, 0 RuboCop offenses, hexagonal layer enforcement, ARCHITECTURE.md included.

Rule of thumb: Business logic lives only in use_cases/. Controllers call use cases; they never touch repositories directly.

9.5 rails-fullstack (Rails API + React Client, paired)

rails-api/              # Hexagonal Rails backend (see 9.4)
react-client/           # React + Vite frontend (see 9.2)

Status (2026-03-08): Fully validated — boots via docker compose up, /health returns 200, frontend connects to backend.

Rule of thumb: Use the wiring/docker-compose.yml to run both services together locally. Each service is independently deployable.

9.6 python-worker-service (FastAPI, stateless)

app/
├── api/                 # FastAPI route handlers
├── workers/             # Audio/AI processing logic
└── core/               # Shared domain utilities

Status (2026-03-08): Newly created — 4/4 tests passing. Stateless audio/AI processing worker. Accepts multipart POST requests from Rails via HTTP. PRO tier.

Rule of thumb: This service is intentionally stateless — no database. It receives a file or payload, processes it, and returns a result. Designed to be called by rails-api or rails-fullstack via HTTP multipart POST.

9.7 Architecture diagram (high level)

flowchart LR
    User --> Web[React Client]
    Web --> API[Python SaaS API]
    API --> Core[Domain Core]
    API --> Infra[Infrastructure Adapters]
    Infra --> DB[(Database)]

9.8 Local workflow checklist

Use this quick checklist when you start or resume work:

• Pull latest changes from Git.
• Install dependencies (pip install -r requirements.txt, npm install).
• Verify environment variables are loaded.
• Start backend and confirm it responds.
• Start frontend and confirm it loads.
• Run tests before committing.

---

10. Feature Enable Example

Many features are added at scaffold time using flags. For example, to create a Python SaaS project with commerce and a tunnel for webhook testing:

sscli new \
  --template python-saas \
  --name shop-api \
  --with-commerce \
  --with-tunnel

This injects the feature modules, wiring, and configuration scaffolding for you so you do not have to add them manually later.

Another example (Rails API)

sscli new \
  --template rails-api \
  --name retail-api \
  --with-commerce \
  --with-tunnel

Add Stripe payments (--with-payment)

sscli new \
  --template python-saas \
  --name billing-api \
  --with-payment

This injects a Stripe Checkout session endpoint and a webhook handler. Fill in the STRIPE_* variables in .env before starting the service.

How to decide which features to enable

• Start with the smallest set that supports your immediate goals.
• Add commerce only if you plan to process payments now.
• Add a tunnel if you need to test webhooks locally.

---

11. Testing

You should run tests early and often. Each template includes sensible defaults.

11.1 Backend (python-saas)

pytest

11.2 React Client

npm run test
npm run test:e2e

11.3 Static Landing

npm run test:e2e

If a template includes additional linting or type checks, they will be listed in its RUNBOOK.md.

Suggested testing cadence

• Run unit tests after every meaningful change.
• Run E2E tests before each deployment.
• Keep test runs short and frequent to avoid long debugging sessions.

What to do when tests fail

• Read the first error message carefully.
• Re-run only the failing test to confirm it is reproducible.
• Fix the smallest possible piece first, then expand.
• If you are unsure, look for a similar test in the same folder.

---

12. Command Cheat Sheet

sscli --version                    # Show installed version
sscli interactive                  # Guided setup
sscli explore                      # Browse templates
sscli new --template <name>         # Create a project
sscli login                         # Authenticate
sscli whoami                        # Show account info
sscli logout                        # Sign out

Local project commands (common)

npm run dev                          # Start local frontend dev server
npm run build                        # Build frontend for production
docker build -t my-app .             # Build a Docker image
docker run -p 8080:80 my-app          # Run a Docker image locally

---

13. Troubleshooting

Problem: sscli command not found

• Ensure your Python bin directory is in PATH.
• If you installed with pipx, run pipx ensurepath and restart your terminal.

Problem: sscli login fails

• Confirm you can reach the network and the service domain.
• Try running sscli whoami to see if the session is already active.

Problem: Docker build fails

• Make sure Docker Desktop is running.
• Restart Docker if it is stuck or unresponsive.
• Run docker system prune only if you understand the impact.

Problem: Node version mismatch

• Run node --version and ensure it is 18+.
• Use a version manager (nvm, fnm, or asdf) if needed.

Problem: Port already in use

• Identify the process with lsof -i :PORT and stop it.
• Or change the port in your run command.

Problem: Template download failed

• Verify you are logged in with sscli whoami.
• Check your network connection.

Problem: Frontend cannot reach backend

• Make sure the backend is running on the port you expect.
• Confirm the frontend API base URL uses the correct host and port.
• Check CORS settings on the backend.

Problem: Build succeeds locally but fails in hosting

• Confirm the hosting provider uses the correct build command.
• Confirm the output directory is dist/.
• Check if the hosting provider requires Node 18+.

---

14. Next Steps

• Read the RUNBOOK.md in each template for detailed guidance.
• Explore optional features such as commerce, auth, and tunnel support.
• Decide on a deployment strategy for staging and production.
• Set up CI/CD once you are ready for a repeatable release path.
• Review compliance requirements if you handle user data.
• Start a private Git repository and commit your project early.
• Create a staging environment before production.

Suggested progression

1. Ship a landing page.
2. Add a backend API.
3. Add a React client.
4. Add features like commerce or auth when needed.

---

15. Beginner Tips

• Start with sscli interactive if you are unsure which template to pick.
• Start with static-landing, then move to python-saas and react-client.
• Keep changes small and incremental as you learn the stack.
• Check every template folder for a RUNBOOK.md before going deeper.
• Build locally, then deploy. Do not skip the production build step.

If you feel stuck

• Re-read the section slowly and run commands one at a time.
• Use a clean terminal session to avoid confusing environment issues.
• Ask for help with exact error messages and the command you ran.

---

16. FAQ

Q: How long does it take to deploy the landing page? Most beginners can deploy a landing page in 20 to 30 minutes. The fastest path is Vercel or Netlify because you can deploy with a single command and a short configuration prompt.

Q: Do I need Docker for the landing page? You can develop and deploy without Docker, but Docker is the official production path in all templates. If you plan to deploy to a container platform later, use Docker early so the build is consistent.

Q: Can I skip authentication? Authentication is required to scaffold templates and access features. Once a project is generated, you can work on it without being logged in, but you will not be able to scaffold new templates.

Q: I do not see my changes on the page. What should I check? First, confirm you edited the correct file and saved it. Then check the terminal to see if the dev server is still running. If the dev server is running but the page does not update, restart it with npm run dev.

Q: Where do I change the site theme? Most landing templates store theme settings in blueprint.json. Look for a theme field or a theme selector near the top of the file.

Q: Which files should I avoid editing first? If you are new, avoid editing build scripts and configuration files such as astro.config.mjs and tailwind.config.mjs until you are comfortable. Start in blueprint.json or src/components/.

Q: How do I update dependencies safely? If you need to update dependencies, do it in a small, isolated step. For Node projects, update one package at a time and run tests after each change. For Python projects, update one dependency in requirements.txt and run pytest. This keeps the blast radius small and makes rollbacks easier.

Q: What should I do with .env files? Do not commit real secrets. Create a .env.example file with placeholders and commit that instead. For local development, keep .env files outside Git or add them to .gitignore. In production, use your hosting provider settings to store secrets.

Q: Can I rename a project after I create it? Yes, but keep it simple. Rename the folder, update any references in README files, and update any environment variables that include the project name. If you have already deployed, consider creating a new project to avoid confusion.

Q: How do template updates work? Templates are generated at scaffold time and are not auto-updated. If a template receives improvements later, you can compare changes manually or regenerate a new project and copy your modifications. This keeps your project stable and avoids surprise changes.

Q: Where do I report issues or request features? Use the documentation index to locate the appropriate guide, then check for a troubleshooting section. If you still need help, collect the exact command you ran and the full error output. That makes it easier for maintainers to reproduce the issue.

Q: What is the fastest safe path to production? Start with a landing page deploy, then add a backend, then add a frontend. This keeps each step small and lets you verify deployment mechanics early. Do not try to deploy everything in one step. The smaller the change, the easier it is to fix when something goes wrong.

Q: Should I use the interactive mode or direct commands? Use sscli interactive if you are unsure which template to pick or which flags to enable. Use direct commands if you already know the template and want repeatable scripts. Many teams use interactive for exploration and direct commands for automation.

Q: Can I use these templates without Docker? Yes for local development, but Docker is the official production path. Even if you skip Docker early, consider using it before the first deployment so you can match the production environment more closely.

Q: How do I connect the React frontend to the backend? Set the API base URL in the frontend environment file or API client configuration, then confirm the backend is running. Most clients read VITE_API_BASE_URL by default.

Q: What if I need a database? The python-saas template supports database adapters. Check the template RUNBOOK.md and environment variables for database configuration. You can start with SQLite for development and move to Postgres later.

Q: How do I deploy the full-stack app? Start by deploying the backend as a Docker container and the frontend as a static site. Once both are stable, move to a managed platform or add infrastructure tooling. This guide focuses on the landing page deployment because it is the fastest path for beginners.

Q: Where do I find more documentation? Start with INDEX.md for a map of the user-facing docs. Then read the RUNBOOK.md in each template for detailed setup steps.

---

17. Appendix: Glossary

Adapter: A component that connects your core logic to an external system like a database or API.

CLI: Command line interface. In this guide, sscli is the CLI.

CORS: Browser security policy that can block frontend requests to a backend on another host or port.

Docker image: A packaged build of your application that runs consistently anywhere Docker is installed.

Infrastructure: External systems like databases, message queues, or third-party APIs.

Landing page: A static marketing page designed to describe and sell a product.

Template: A pre-built project scaffold with best practices and a deployable setup.

Use case: A unit of business logic that performs a specific action in the domain.

---

Need More Help?

• See the public documentation index: INDEX.md
• Review template-specific docs in each template directory
• Check troubleshooting in TROUBLESHOOTING.md