Skip to content
Engineering

Platform Architecture & Monorepo Overview

1. Executive Summary

Section titled “1. Executive Summary”

GERCIA (GERCIA Engenharia de Software Ltda, CNPJ: 67.539.717/0001-87) is an enterprise software engineering company operating a high-performance multi-vertical SaaS platform monorepo (Plataforma GERCIA). The foundation layer (Foundation/) provides an industry-agnostic SaaS engine designed to host pluggable business verticals.

The Healthcare vertical (Health/) is the flagship business vertical, responsible for the triangulation between Doctors (Clinical), Patients (Mobile), and Compounding Pharmacies (Pharmacy).

The platform orchestrates four specialized product pillars:

  1. GERCIA Care (care.gercia.com.br): The premier mobile application (Kotlin Multiplatform with native SwiftUI on iOS and Jetpack Compose on Android) uniting Classes A and B patients with clinicians via a dual-persona architecture. Integrates longitudinal health records, compounding quotations, and smartwatch health telemetry (Apple HealthKit & Health Connect) in Patient Mode, with an on-the-go Clinician Companion Mode featuring schedule triage, clinical AI copilot, and hardware-backed push-to-sign biometric authentication (Apple Secure Enclave / Android Keystore) for desktop prescription issuance.
  2. GERCIA Hub (Gercia.Edge): The physical hardware and bench automation edge agent running locally on clinic and laboratory workstations, orchestrating analytical balances (Gehaka, Marte, Mettler Toledo), thermal label printing (Epson, Zebra), specimen tube barcoding, and continuous cold-chain IoT temperature telemetry.
  3. GERCIA Vet (gercia.vet.br / app.gercia.vet.br): The sovereign veterinary healthcare vertical dedicated to veterinary clinics, pet hospitals, equine centers, and veterinary compounding pharmacies, operating in strict compliance with MAPA (Ministério da Agricultura e Pecuária) and CFMV standards (institutional portal at gercia.vet.br, B2B SaaS application at app.gercia.vet.br).
  4. GERCIA Dental: The specialized dental healthcare vertical operating within app.gercia.com.br dedicated to dental clinics, odontological centers, and oral surgery practices, operating under CFO (Conselho Federal de Odontologia) and CRO standards, featuring visual Odontograms, periodontal charting, and specialized dental compounding.

2. Multi-Vertical Monorepo Topology

Section titled “2. Multi-Vertical Monorepo Topology”
flowchart TD
    subgraph FoundationLayer ["Universal Platform Foundation (Foundation/)"]
        BB["Gercia.BuildingBlocks<br>(Universal DDD Primitives)"]
        CORE["Gercia.Core<br>(Tenancy, Postgres RLS, Master Identity, AES Crypto, GCS)"]
    end
    
    subgraph VerticalsLayer ["Pluggable Business Verticals (dotnet/src/)"]
        HEALTH["Healthcare Vertical (Health/)<br>• Gercia.Clinical (CRM, CREFITO, CRN, Telehealth)<br>• Gercia.Pharmacy (Formulas, SGQ, CoA, Balances, Waste)<br>• Gercia.Dental (Odontograms, Periodontics, CFO/CRO)"]
        OPS["Operations Domain (Operations/)<br>• Gercia.Operations (PLG Freemium, Reverse Trial, Billing)"]
        VET["Veterinary Vertical (Veterinary/)<br>• Gercia.Veterinary (gercia.vet.br / app.gercia.vet.br / MAPA)"]
    end
    
    subgraph HostsLayer ["Backend Orchestration Host (dotnet/src/Hosts/)"]
        SERVER["Gercia.Server (ASP.NET Core .NET 10)<br>Universal Cloud Server • REST, MCP AI & Migrations"]
    end

    subgraph ProductsLayer ["Presentation & Edge Products (apps/ & dotnet/src/Edge/)"]
        WEB["@gercia/app (apps/app)<br>Angular 22 SPA • PrimeNG 22 • Tailwind v4<br>Cloudflare Pages (app.gercia.com.br / app.gercia.vet.br)"]
        CARE["GERCIA Care (apps/mobile - Roadmap)<br>Kotlin Multiplatform (KMP)<br>SwiftUI (iOS) • Jetpack Compose (Android)"]
        HUB["GERCIA Hub (dotnet/src/Edge/Gercia.Edge)<br>Local Station Agent • Scales, Thermal Printers, IoT"]
    end

    BB --> CORE
    CORE --> HEALTH
    CORE --> OPS
    CORE --> VET

    HEALTH --> HostsLayer
    OPS --> HostsLayer
    VET --> HostsLayer

    HostsLayer --> WEB
    HostsLayer --> CARE
    HostsLayer <--> HUB

3. Physical Directory Structure

Section titled “3. Physical Directory Structure”
gercia-platform/
 ├── .agents/                      # Architecture guidelines, Linear orchestration, and AI agent rules
 ├── apps/                         # User-facing frontend applications and mobile clients
 │    ├── app/                     # Enterprise B2B SaaS SPA (@gercia/app, app.gercia.com.br & app.gercia.vet.br) in Angular 22
 │    ├── site/                    # Institutional public portal (@gercia/site, gercia.com.br) in Astro 7 & Svelte 5
 │    ├── site-vet/                # Sovereign veterinary public portal (@gercia/site-vet, gercia.vet.br) in Astro 7 & Svelte 5
 │    ├── status/                  # Sovereign out-of-band public Status Page (@gercia/status) in Astro 7, Svelte 5 & Cloudflare D1
 │    └── mobile/                  # Companion mobile client (GERCIA Care) in Kotlin Multiplatform (SwiftUI & Compose)
 ├── deploy/                       # Centralized Google Cloud Build CI/CD pipelines
 │    ├── cloudbuild.dotnet.yaml   # .NET 10 SaaS unified server pipeline (Gercia.Server)
 │    ├── cloudbuild.docs.yaml     # Private & Public docs Starlight deployment
 │    ├── cloudbuild.status.yaml   # Status page Cloudflare Pages deployment
 │    └── cloudbuild.site.yaml     # Public website Cloudflare Pages deployment
 ├── docs/                         # Documentation portals built with Astro Starlight
 │    ├── private/                 # Internal Engineering & Architecture Portal (docs-stg / eng.gercia.com.br)
 │    └── public/                  # Public Help Center & User Manuals (docs.gercia.com.br)
 ├── dotnet/                       # Enterprise .NET 10 Ecosystem (C# 14 / .NET 10)
 │    ├── Gercia.slnx              # Master universal solution file
 │    ├── Gercia.Server.slnf       # Backend server solution filter (Server, Edge, Modules)
 │    ├── Gercia.UnitTests.slnf    # Fast unit & architecture test suite filter
 │    ├── src/
 │    │    ├── Foundation/         # Universal SaaS Platform Engine (Schema: core)
 │    │    │    ├── Gercia.BuildingBlocks/ # Universal DDD primitives (Entity, ValueObject, UnitOfWork)
 │    │    │    └── Gercia.Core/           # Multi-tenancy, Postgres RLS, User Identity, AES Crypto, GCS
 │    │    ├── Operations/         # Operations Domain (Schema: operations)
 │    │    │    └── Gercia.Operations/     # SaaS billing, PLG Freemium, 30-Day Reverse Trial, contracts
 │    │    ├── Health/             # Healthcare Vertical (Schemas: clinical, pharmacy, dental)
 │    │    │    ├── Gercia.Clinical/   # Multidisciplinary clinical domain (CRM, CREFITO, CRN, Telehealth)
 │    │    │    ├── Gercia.Pharmacy/   # Compounding pharmacy domain (Formulas, SGQ, CoA, Balances, Waste)
 │    │    │    └── Gercia.Dental/     # Specialized dental domain (Odontograms, Periodontics, CFO/CRO)
 │    │    ├── Veterinary/         # Sovereign Veterinary Vertical (Schema: veterinary)
 │    │    │    └── Gercia.Veterinary/ # Veterinary care, species/breeds, CFMV prescriptions, MAPA
 │    │    ├── Hosts/              # Application Orchestration Host
 │    │    │    └── Gercia.Server/     # Unified Cloud Server (REST, OpenIddict STS, MCP, Migrations)
 │    │    └── Edge/               # Local Hardware Edge Agent (GERCIA Hub)
 │    │         └── Gercia.Edge/       # Serial scales, thermal labels, cold-chain IoT, tube labeling
 │    └── tst/                     # Automated Test Suites (xUnit, FluentAssertions, NetArchTest)
 │         ├── Foundation/         # BuildingBlocks & Core unit/integration tests
 │         ├── Health/             # Healthcare vertical automated tests (Clinical, Dental)
 │         └── Veterinary/         # Sovereign veterinary vertical automated tests
 ├── package.json                  # Unified Root pnpm Workspaces (apps/*, docs/*)
 ├── pnpm-workspace.yaml           # pnpm workspace configuration & script security
 └── pnpm-lock.yaml                # Single monorepo pnpm lockfile

4. Strict Dependency Boundaries (Clean Architecture)

Section titled “4. Strict Dependency Boundaries (Clean Architecture)”

To maintain clean hexagonal boundaries, monorepo dependencies must strictly adhere to the following rules:

  1. BuildingBlocks: Bottom-most layer. Zero references to any other project in the solution.
  2. Core: Universal platform engine. Can only reference BuildingBlocks. Zero business vertical dependencies.
  3. Gercia.Clinical, Gercia.Pharmacy, Gercia.Dental, Gercia.Veterinary, Gercia.Operations: Independent business modules. They can reference Core and BuildingBlocks. Zero circular cross-dependencies between each other.
  4. Hosts (Server): Orchestration layer. Can reference business verticals, Core, and BuildingBlocks to register DI services and expose endpoints.
  5. Edge (Gercia.Edge): Local physical agent running on workstations. Communicates directly with local browsers via HTTP/SSE (127.0.0.1:5050) and cloud servers via authenticated REST outbox long-polling. Zero direct database or entity references.
  6. Frontends & Mobile Clients (@gercia/app, GERCIA Care): Fully decoupled applications communicating exclusively over HTTPS/WSS via REST API and OpenIddict STS.

5. Pluggable Multi-Vertical SaaS Framework

Section titled “5. Pluggable Multi-Vertical SaaS Framework”

GERCIA does not operate as a single-purpose clinical application. It is engineered as a Universal SaaS Platform Engine hosting autonomous, pluggable business verticals. The healthcare domain is organized as an extensible Healthcare Verticals Ecosystem (Ecossistema de Verticais de Saúde), designed to expand across all segments of the health economy.

Healthcare Verticals Taxonomy & Roadmap

Section titled “Healthcare Verticals Taxonomy & Roadmap”
flowchart TD
    subgraph FOUNDATION ["Universal Platform Foundation (Gercia.BuildingBlocks & Gercia.Core)"]
        F1["Tenancy & Postgres RLS (core.tenants)"]
        F2["Master Civil Identity (core.users)"]
        F3["Cryptographic Engine & Column AES-256-GCM"]
        F4["Distributed Auditing (core.audit_history)"]
    end

    subgraph HEALTH_VERTICALS ["Healthcare Verticals Ecosystem (dotnet/src/Health/)"]
        direction TB
        V1["1. Clinical Domain (Gercia.Clinical)<br>Medical practices, polyclinics, telemedicine, EHR<br>PostgreSQL Schema: clinical"]
        V2["2. Compounding Pharmacy Domain (Gercia.Pharmacy)<br>Galenic formulations, cleanroom workstations, RDC 67<br>PostgreSQL Schema: pharmacy"]
        V3["3. Dental & Odontology (Gercia.Dental)<br>Odontograms, dental charting, prosthetics, CFO/CRO<br>PostgreSQL Schema: dental"]
        V4["4. Diagnostics & Pathology (Gercia.Diagnostics - Roadmap)<br>Clinical labs, imaging, sample tracking<br>PostgreSQL Schema: diagnostics"]
    end

    subgraph VET_VERTICAL ["Sovereign Veterinary Vertical (dotnet/src/Veterinary/)"]
        VET_DOM["Veterinary Medicine (Gercia.Veterinary)<br>Pet & livestock care, CRMV prescriptions, MAPA, SIPEAGRO<br>PostgreSQL Schema: veterinary • gercia.vet.br / app.gercia.vet.br"]
    end

    subgraph CLIENT_LAYER ["Cross-Vertical Client Experience"]
        WEB["@gercia/app (apps/app)<br>Angular 22 SPA • PrimeNG 22 • Tailwind v4<br>Cloudflare Pages (app.gercia.com.br / app.gercia.vet.br)"]
        MOBILE["GERCIA Care (apps/mobile - Roadmap)<br>Kotlin Multiplatform (KMP)<br>SwiftUI (iOS) • Jetpack Compose (Android)"]
        EDGE_AGENT["GERCIA Hub (dotnet/src/Edge/Gercia.Edge)<br>.NET 10 Daemon • Balances, Thermal Printers, Sensors"]
    end

    subgraph OPERATIONS ["Platform Operations Vertical (dotnet/src/Operations/)"]
        OPS_DOM["Gercia.Operations<br>SaaS Subscriptions, Multi-Tenant Billing, Contracts<br>PostgreSQL Schema: operations"]
    end

    FOUNDATION ==> HEALTH_VERTICALS
    FOUNDATION ==> VET_VERTICAL
    FOUNDATION ==> OPERATIONS
    HEALTH_VERTICALS -.-> WEB
    HEALTH_VERTICALS -.-> MOBILE
    HEALTH_VERTICALS -.-> EDGE_AGENT
    VET_VERTICAL -.-> WEB
    VET_VERTICAL -.-> MOBILE
    VET_VERTICAL -.-> EDGE_AGENT

Outpatient Focus & Zero Hospital ERP Scope Invariant

Section titled “Outpatient Focus & Zero Hospital ERP Scope Invariant”

The GERCIA Platform is engineered exclusively for outpatient clinical practice (individual consultórios, integrated medical clinics, polyclinics, dental clinics, veterinary practices) and compounding pharmacies.

[!IMPORTANT] ZERO HOSPITAL ERP SCOPE GERCIA does NOT develop, sell, or operate inpatient hospital software systems. The platform contains zero features for inpatient bed management (gestão de leitos), hospital ward nursing rounds (enfermarias), electronic Medication Administration Records (eMAR em leito), hospital operating rooms (centro cirúrgico hospitalar), or hospital emergency rooms (pronto-socorro hospitalar).

The sole touchpoint between GERCIA and hospitals is external health record interoperability: providing secure, patient-consented read-only access or export of outpatient consultation history and digital prescriptions (via open standards such as FHIR, HL7, or signed PAdES PDFs) to hospital admission teams via the GERCIA Care mobile application or external healthcare gateways.

Architectural Blueprint for Provisioning a New Vertical

Section titled “Architectural Blueprint for Provisioning a New Vertical”

Whenever a new healthcare vertical (e.g., Health.Diagnostics) or an enterprise business vertical (e.g., Legal.Contracts) is introduced into the monorepo, it must strictly follow this 6-step blueprint:

  1. Directory & Monorepo Isolation: Created under its top-level vertical directory (dotnet/src/Health/Gercia.<VerticalName>/ or dotnet/src/<VerticalCategory>/Gercia.<VerticalName>/).
  2. Dedicated Database Schema: Mapped to an exclusive PostgreSQL schema (CREATE SCHEMA <vertical_name>;). Tables must never pollute the shared core schema.
  3. Sovereign EF Core DbContext & Unit of Work: Exposes an isolated DbContext implementing IUnitOfWork, applying configurations from its own assembly via ApplyConfigurationsFromAssembly().
  4. Dynamic Postgres RLS Interceptor: Automatically registers the TenantRowLevelSecurityInterceptor, ensuring every query and mutation executes under the active tenant’s context (SET LOCAL app.current_tenant_id = '<guid>').
  5. Zero Cross-Module Coupling: Modules must communicate across vertical boundaries exclusively via published integration events (IDomainEvent) or public contracts. A vertical must never directly reference the database context or internal models of another vertical.
  6. Unified Host & Presentation Registration: Application endpoints and MCP tools are registered in Gercia.Server, while user-facing workflows are exposed in @gercia/app (Angular 22 SPA) using Standalone Components, reactive Signals, and PrimeNG 22.