Docs / Set up your org

Setting up & managing projects

A project usually maps to a business domain such as Billing Platform, Identity, or Catalog. It is the middle of REEZN’s hierarchy: it holds the services a domain is built from, and it is where features are created, tracked, and moved through the workflow.

Creating and managing projects is an admin job. Only an org admin can create a project or change its settings (services, repositories, and review policy), and a brand-new project is visible to admins alone until a team grants other people access. So setting a project up and giving people somewhere to work in it are two deliberate steps.

What a project contains

Name: A short label for the domain, for example “Billing Platform.” The one required field; everything else can be added now or later.
Description: An optional one-line summary of what the domain does, for example “Subscriptions, invoicing, dunning, and revenue recognition.” Shown on the project card.
Services: The deployable units the domain is built from. A feature belongs to one or more services, and each service it touches gets its own REASONS canvas.
Review policy: How sign-off works for features in this project: who must approve each artifact, and whether self-approval is allowed.

A project also has a stable ID that appears in its URLs. It is set when the project is created and can’t be changed afterward; the name is free to change, the ID is not.

Creating a project

From your org home, choose New project. The form walks through a few sections, but only the name is strictly required; the rest you can fill in now or add later from project settings:

Name the project, and optionally add a one-line description of what the domain does.
Add at least one service, with a name and a tech stack: free text, with suggestions for common stacks (NestJS, Next.js, FastAPI, Spring Boot, Rails, and the like). Write it the way you would describe it to a new teammate: languages, frameworks, datastores, anything that shapes how code is written there. Use “Add another service” for as many as the domain needs; a feature can span several, each getting its own canvas.
Optionally give a service a GitHub repository and a read-only token, so plans for that service are grounded in your actual code.
Pick a review policy that matches how your team approves work. It defaults to Balanced.
Create the project. It is created admin-only, with an empty access list, until a team grants other members access.

The org’s norms and safeguards library is inherited automatically by every new project; you can layer project-scoped norms and safeguards on top later. There is nothing to wire up here.

Services

A service is a deployable unit, usually a codebase. It is the level a REASONS canvas is generated for, so the services you list are what a feature’s plans get split across. Each service carries a few fields:

Service name: A short label, for example “Billing API.” Required for the service to be saved.
Tech stack: Free text describing what the service is built with: languages, frameworks, datastores (for example “TypeScript · NestJS · PostgreSQL”). Common stacks are offered as suggestions as you type. The analysis and the canvas for this service are written in terms of this stack rather than a generic one.
Repository: Optional. A GitHub repo as org/service-name (prefixed with github.com/) that enables live code context for this service’s plans.
GitHub token: Optional. A read-only token granting access to the repo above. Planning never writes to your repository; this token only ever reads. (On the Business plan, implementation is opt-in and uses a separate, write-scoped token you add deliberately.)

You can add a service with just a name and stack and leave the repo and token blank; generation still works, it simply won’t have your existing code as context. Add, edit, or remove services any time from Project settings → Services.

Review policy

A project’s review policy sets who must sign off on each artifact before a feature can advance, and whether someone can approve their own work. You pick one of three presets when you create the project, and can change it any time from Project settings → Policy:

Light: 1 approver per artifact, and self-approval is allowed. Best for internal tools and exploratory work, where speed matters more than a second set of eyes.
Balanced (default): 1 feature author approves the analysis, 1 tech reviewer approves the canvas, and no self-approval. The default, and the right fit for most product teams.
Strict: 2 approvers per artifact, and all comments must be resolved before approval. Best for regulated domains where every change needs heavy scrutiny.

The policy tunes how much scrutiny a project asks for: approver counts, self-approval, and whether open comments block a sign-off. Underneath it sits a floor the policy can never lower, whichever preset you choose: approval is always limited to tech reviewers and admins, and that limit is enforced by REEZN’s server-side permission checks rather than the interface.

Managing a project later

Everything chosen at creation is editable afterward from Project settings, which an admin reaches from the project. It is organized into tabs:

General: Rename the project and edit its description. The project ID is shown here too, but it is read-only; it is baked into URLs and can’t be changed.
Services: Add, rename, re-stack, or remove services, and connect or update each one’s GitHub repository and token.
Policy: Switch the review policy between Light, Balanced, and Strict.
Danger zone: Archive the project (hiding it from the sidebar and blocking new features while preserving all data) or permanently delete it along with every feature, analysis, and canvas. Deletion can’t be undone.

Project settings (services, repositories, and review policy) can only be changed by an org admin. A non-admin who opens the settings page sees a notice that admin rights are required; the restriction is enforced server-side, so it holds even for a request that slipped past the UI.

Who can see a project

Creating a project doesn’t hand anyone access to it. A new project’s access list is empty, so at first only admins, who see every project regardless, can reach it. Access for everyone else flows through teams: an admin attaches the project to a team, and every member of that team can then see the project, its services, and every feature, analysis, and canvas within. Drop the project from the team and that reach disappears just as cleanly.

Why this exists

Mapping a project to a business domain keeps related work, and the services it is built from, in one place, while splitting plans per service keeps each blueprint honest about the stack it actually runs on. Keeping project setup admin-only, and starting every project access-free until a team opens it, means access is a deliberate grant rather than an accident of creation. And the per-project review policy lets a regulated domain demand two approvers while an internal tool moves fast, without forcing the whole org onto one setting.