Map the Replit System
Know what Replit is changing, where your work lives, and why a working Preview is not yet a published product.
By the end
A plain-language system map that distinguishes the project, artifact, source files, development process, preview URL, data resources, and published app.
Create and name the practice project
Begin at the signed-in Replit home screen. Choose a Web App output when the selector is visible, paste a one-sentence brief, and let Agent create the project. If you already have a project, open it from Projects instead. Name the project for the job it performs—such as facilities-intake-practice—not for a vague department or technology. You should land in the Project Editor with Agent, the file tree, Run, Console, Shell, and Preview available.
Do not connect a real customer system, production credential, payment method, or sensitive dataset for this course project. Use a personal or intentionally approved workspace and synthetic examples. Before the first Agent message, open the current plan and usage pages so you know which actions consume credits and which publishing choices can create ongoing cost. The guide cannot choose an account budget for you.
- Account: a Replit login you are authorized to use.
- Workspace: the personal or team ownership and billing boundary.
- Project name: the stable job this practice system performs.
- Starting output: Web App for the course's browser-based workflow.
- Practice data: invented names and records only.
Start with containers and outputs
A Replit project is the container for the work. It holds code, data, configuration, conversation context, and one or more things you may eventually publish. Replit calls those publishable outputs artifacts. A web app can be an artifact; so can a mobile app, design, slide deck, or visualization. Files such as a logo or CSV support an artifact, but they are not artifacts by themselves.
This distinction becomes important when one project contains several outputs. Artifacts in the same project can share a backend, database, and file storage, and publishing can move them together. That is convenient for a customer app and its admin dashboard, but wrong for unrelated client products that need separate data and release schedules. Choose the project boundary before the design gets elaborate.
- Project: the collaboration and resource boundary.
- Artifact: a publishable output inside the project.
- File: an ingredient used by the app or its tooling.
- Resource: database, storage, secrets, integrations, and compute the app depends on.
- Release: a specific version made available to real users.
Separate editor, preview, and production
The Project Editor is the workbench. The file editor changes source; Agent can plan and edit; the Shell accepts commands; the Console shows a running program's output; Preview displays the development app. These are different windows into one project, not five copies of the product.
A Preview proves that the development process can render the current workspace. It may stop, restart, contain test data, or rely on development-only configuration. A published app is a separately served release with its own URL and production resources. The sentence 'it works' is incomplete until you name where it works and which user journey you verified.
Understand the Agent loop
Agent is not merely a chat box. In Build mode it can inspect the project, edit files, install dependencies, run the app, test behavior, and checkpoint work. The useful mental model is a loop: brief, plan, action, observation, correction, receipt. You remain the product owner who supplies intent and decides whether the evidence meets the promise.
The project is Agent's context boundary. Do not assume a conversation in one project can see another project, an external service, or a private account. Connections and secrets must be intentionally supplied. That constraint is a safety feature as well as a practical design fact.
Name four layers of proof
Source proof shows that the expected code or configuration exists. Runtime proof shows a process built from that source starts and responds. Workflow proof shows a real user journey changes the right state. Production proof shows the intended release and resources are live at the published URL. Each layer answers a different question.
A green Run button is not a workflow test. A correct Preview is not a production deployment. A published home page is not proof that authentication, permissions, data writes, and recovery work. Mature builders collect the smallest receipt for every material promise instead of using one screenshot as universal evidence.
Choose the project boundary
Keep outputs together when they represent one product, share data and server logic, and should ship together. Separate them when they serve different owners, contain unrelated sensitive data, need independent access controls, or must deploy on different schedules. Moving an artifact later may not be a simple click, so this is an early product decision rather than tidying.
Write the boundary down in one sentence: 'This project owns the intake workflow, its authenticated operator dashboard, and the shared database; it does not own billing or the public marketing site.' That sentence gives Agent a map and gives future collaborators a way to reject accidental scope creep.
Working reference
Commands and patterns
Read-only project orientation
pwd find . -maxdepth 2 -type f | sort | head -80 printenv | cut -d= -f1 | sort
Use the Shell to identify the working directory, a shallow file map, and environment-variable names. Never print secret values into a transcript or screenshot.
When the happy path breaks
Failure modes
Symptom
The app looks correct in Preview, but the public URL is old or broken.
Likely cause
Preview and the published release were treated as the same environment.
Recovery
Name the target environment, publish a new release, then repeat the critical journey at the published URL.
Symptom
Two unrelated products share data, secrets, or a release unexpectedly.
Likely cause
They were created as artifacts inside one project without an explicit lifecycle boundary.
Recovery
Document ownership and deployment needs first; use separate projects when data or release independence matters.
Symptom
Agent says a task is finished, but nobody can show the behavior working.
Likely cause
Completion was defined as file changes rather than observable acceptance checks.
Recovery
Require source, runtime, workflow, and production receipts appropriate to the change.
Hands-on lab
Draw the map of one app
Open an existing Replit project or create an empty practice project, then identify every part of the system without changing code.
- 01Sign in, choose Web App from the home-screen output selector when offered, enter a one-sentence practice brief, and open the resulting Project Editor. If using an existing project, record why it is safe for practice.
- 02Rename the project for its job, then write its one-sentence purpose and name its workspace owner and intended users.
- 03List each artifact and the data, backend, storage, secrets, and integrations it depends on.
- 04Locate the Project Editor, file tree, Run control, Console, Shell, Preview, Publishing tool, and version history.
- 05Record the development URL and, if one exists, the published URL. Label them explicitly.
- 06Choose one user journey and list the proof required at source, runtime, workflow, and production layers.
Deliverable: A one-page system map another person can use to explain where the app lives and what 'working' would mean.
Reusable artifact
Replit system map
Copy this before the first serious build and update it when the project boundary changes.
PROJECT: [name] PURPOSE: [one observable business outcome] OWNER / USERS: [who operates it] / [who benefits] ARTIFACTS: [publishable outputs] SHARED RESOURCES: [database, backend, storage] EXTERNAL SYSTEMS: [APIs and connectors, no credentials] DEVELOPMENT URL: [preview] PRODUCTION URL: [published app or not published] BOUNDARY: This project owns [...] and does not own [...]. CRITICAL JOURNEY: Given [...], when [...], then [...].
Before you move on
Receipt checklist
- A labeled diagram or table distinguishes project, artifact, files, resources, Preview, and published app.
- The development and production URLs are recorded separately, or production is explicitly marked absent.
- One critical journey has distinct source, runtime, workflow, and production checks.
- The project boundary says both what belongs and what does not.
Primary sources
