Skip to content

System Landscape & Topology

1. The 3-Tier Environment Model

The Singular Dream platform operates on a strictly defined 3-Tier Topology. This model ensures that every change is verified in a safe environment before reaching production users.

Tier Environment Name Branch Environment Prefix Purpose Access Control
1 DEVELOPMENT dev DEV Active development, radical experimentation. Open to Engineering
2 STAGING stg STG Integration testing, "Gatekeeper" verification. Engineering, QA, Product
3 PRODUCTION main PRD Live system, real user data. End Users

2. Resource Naming Conventions

To prevent "drift" and accidental data pollution, all infrastructure resources MUST adhere to the Suffix Strategy.

A. Infrastructure Projects (Vercel, Firebase)

  • Structure: [project-name]-[env-suffix]
  • Examples:
    • singular-dream-dev
    • singular-dream-stg
    • singular-dream-prd (Explicit suffix for project containers)

B. Databases (SQL/NoSQL)

  • Structure: Standard Identifier (No internal prefix)
  • Rationale: The database lives inside the project container. We do not name a table DEV_USERS inside the singular-dream-dev project.
  • Example: users collection in singular-dream-dev project.

3. The "Golden Path" (CI/CD)

Resources flow in one direction only.

graph LR
    A[Tier 1: DEV] -->|Merge Request| B{Tier 2: STG}
    B -->|Automated Tests| B
    B -->|Preview & QA| B
    B -->|Approval| C[Tier 3: MAIN]
    C -->|Deploy| D[Production]

Gate Definitions

  • Commit Gate: Local linting and type-checking (Husky).
  • Staging Gate (stg): This is a Place, not an activity.
    • Activity: Automated Testing (stg pipeline)
    • Activity: Preview Deployment (stg URL)
    • Activity: Manual QA
  • Production Gate (main): The Final State. Merging here triggers immediate deployment to Live.