Skip to content

Latest commit

 

History

History

architecture

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
README.md
README.md
 
 
versioning-strategy.md
versioning-strategy.md
 
 

README.md

Architecture Documentation

This directory contains architectural documentation for the GeniusTechSpace API Contracts repository.

Documents

Monorepo Structure

Details on how the monorepo is organized for proto definitions and multi-language clients.

Client Generation

How client code is generated from proto files for each supported language.

Versioning Strategy

API versioning approach and backward compatibility guarantees. Important: Explains why we use both directory-based (v1/, v2/) and Buf versioning - they serve different purposes and both are necessary.

Multitenancy Architecture

Deep dive into the multitenancy model and tenant isolation.

Key Architectural Decisions

1. Proto-First Design

All APIs are defined using Protocol Buffers (proto3) as the source of truth. Client code is generated from these definitions, ensuring consistency across all languages.

2. Multi-Language Support

The repository generates clients for:

  1. Rust (primary) - High-performance services
  2. Go - Backend microservices
  3. Python - ML/Data services and tooling
  4. TypeScript - Web clients and Node.js services
  5. Java - Enterprise integration

3. Modular Package Structure

Each proto module (core, idp, notification, etc.) becomes a separate, independently installable package in each language. This allows consumers to install only what they need.

4. Workspace-Based Monorepos

Each language uses its native workspace/monorepo tooling:

  • Rust: Cargo workspace
  • Go: Go modules with separate go.mod per package
  • Python: pip-installable packages with pyproject.toml
  • TypeScript: npm workspaces
  • Java: Maven multi-module project

5. Dual Versioning Strategy

  • Proto API Versioning: Directory-based (v1, v2, etc.) for API evolution
    • Enables multiple API versions to coexist
    • Allows gradual client migration
    • Industry standard approach
  • Module Versioning: Semantic versioning via Buf for releases
    • Tracks module changes over time
    • Manages dependencies
    • Ensures reproducible builds
  • Both are necessary - they serve different purposes (see Versioning Strategy)

6. Enterprise Standards

  • Comprehensive documentation requirements
  • Input validation on all fields
  • Standardized error handling
  • Audit logging built-in
  • Compliance support (GDPR, HIPAA, SOC 2, PCI DSS)

Directory Structure

api-contracts/
├── proto/                    # Proto definitions (source of truth)
│   ├── core/v1/             # Core infrastructure types
│   ├── idp/v1/              # Identity Provider
│   └── [services]/v1/       # Business services
│
├── clients/                 # Generated clients
│   ├── rust/                # Rust workspace
│   ├── go/                  # Go modules
│   ├── python/              # Python packages
│   ├── typescript/          # TypeScript/npm workspace
│   └── java/                # Maven multi-module
│
├── docs/                    # Documentation
├── scripts/                 # Build and automation scripts
└── tests/                   # Integration tests

Build Pipeline

Proto Files → buf lint → buf generate → Multi-language Clients → Tests → Publish

Related Documentation