Local Development, Tooling & Container Architecture

1. Local Developer Architecture & Philosophy

The GERCIA monorepo enforces deterministic, reproducible local development environments across all engineering workstations. While production and staging operate entirely serverless on Google Cloud Platform (Cloud Run & Cloud SQL) and Cloudflare Pages (see ADR-007), local development mirrors cloud invariants using lightweight local containers, fast developer scripts, and solution filters:

flowchart TD
    subgraph WORKSTATION ["Developer Workstation (Windows / macOS / Linux)"]
        BOOTSTRAP["./start-dev.ps1<br>(1-2s Instant Validation & Tool Sync)"]
        
        subgraph FRONTEND ["Frontend Workspaces (pnpm v12+)"]
            WEB["apps/app (@gercia/app • Angular 22)"]
            SITE["apps/site (@gercia/site • Astro 7)"]
            SITE_VET["apps/site-vet (@gercia/site-vet • Astro 7)"]
            STATUS["apps/status (@gercia/status • Astro 7 & Svelte 5)"]
            DOCS["docs/private & docs/public (Starlight)"]
        end

        subgraph BACKEND ["Backend Ecosystem (.NET 10 / C# 14)"]
            SLNF_SRV["Gercia.Server.slnf<br>(Hosts, Domains & Edge)"]
            SLNF_TEST["Gercia.UnitTests.slnf<br>(Fast Unit & Arch Tests)"]
        end

        subgraph CONTAINERS ["Local Development Containers (Docker Engine)"]
            PG_LOCAL[("Local PostgreSQL 18 Container<br>Port 5432 • Matching Cloud SQL RLS & Extensions")]
        end
    end

    BOOTSTRAP --> FRONTEND
    BOOTSTRAP --> BACKEND
    BOOTSTRAP --> CONTAINERS

---

2. Developer Bootstrap Workflow (start-dev.ps1)

Developers and AI agents initialize their environment via .\start-dev.ps1. The script executes in 1–2 seconds and enforces tooling parity:

# Standard daily initialization (instant verification)
.\start-dev.ps1

# Check for SemVer-compatible workspace updates & Angular CLI migrations
.\start-dev.ps1 -CheckWorkspaceUpdates

# Update global developer tools explicitly
.\start-dev.ps1 -UpdateTools

Automated Verifications Performed:

1. UTF-8 Output Encoding: Sets [Console]::OutputEncoding = UTF-8 to eliminate console Unicode corruption.
2. Global CLI Tools: Verifies required tools: lefthook (v2.2+), pnpm (v12+), csharpier (v1.3+), dotnet-outdated (v4.8+), and dotnet-ef (v10+).
3. Local .NET Manifest Tools: Restores project-pinned tools via dotnet tool restore.
4. Antigravity MCP Configuration: Synchronizes monorepo MCP servers from .agents/mcp_config.json into the global agent configuration directory (~/.gemini/config/mcp_config.json).
5. Git Hooks Synchronization: Installs and syncs fast pre-commit hooks via Lefthook (lefthook.yml), ensuring automatic CSharpier formatting on staged .cs files prior to commit.
6. Antigravity IDE Tooling Standardization: Standardizes engineering workstations exclusively on Google Antigravity IDE and autonomous agent orchestration (.agents/), permanently retiring legacy third-party editor configurations (JetBrains Rider, Cursor).

---

3. Local Containerization (PostgreSQL Emulation)

To match Google Cloud SQL behavior without incurring cloud costs during daily development, local workstations run a local PostgreSQL container:

• Engine Parity: PostgreSQL 18 container matching the Cloud SQL version and collation (en_US.UTF-8).
• Extension Parity: Preloaded with uuid-ossp, pgcrypto, and pgvector.
• Tenant RLS Parity: Executes the same TenantRowLevelSecurityInterceptor enforcing Row-Level Security on every query.
• Launch Settings: Gercia.Server targets this local container under the Development profile declared in launchSettings.json.

---

4. Solution Filters & Workload Segregation (.slnf)

To maintain sub-second compilation and eliminate heavy mobile dependencies from backend development, the repository segregates Visual Studio and CLI workloads using Solution Filters:

Filter Name	Target Projects	Primary Use Case	CLI Build Command
Gercia.slnx	Universal Master Solution (All backend projects)	Full monorepo backend compilation	dotnet build dotnet/Gercia.slnx
Gercia.Server.slnf	Backend host (Gercia.Server), domain modules (BuildingBlocks, Core, Operations, Clinical, Pharmacy, Dental, Veterinary), Edge, and tests	Backend engineering and CI/CD compilation	dotnet build dotnet/Gercia.Server.slnf
Gercia.UnitTests.slnf	Fast unit and architecture test suites	Pre-commit validation and CI test execution	dotnet test dotnet/Gercia.UnitTests.slnf

---

5. Unified Root pnpm Workspaces

All frontend web applications and documentation portals are orchestrated through a single root pnpm-workspace.yaml:

packages:
  - 'apps/*'
  - 'docs/*'

• Compilation: Run pnpm run build at root to compile all 5 portals simultaneously.
• Targeted Commands:
  • pnpm run build:app → Builds @gercia/app (Angular 22 SPA)
  • pnpm run build:site → Builds @gercia/site (Astro 7)
  • pnpm run build:site-vet → Builds @gercia/site-vet (Astro 7)
  • pnpm run build:status → Builds @gercia/status (Astro 7 & Svelte 5)
  • pnpm run build:docs → Builds @gercia/docs-private and @gercia/docs-public