Service Dependencies

Overview

Dependencies are the external libraries used by the service.

This page explains how to add dependencies, where they are defined, which registries they use, and key dependencies for Mahaam.

Purpose

The importance of using dependencies comes from:

• Using already-built functionality saves time and effort.
• The app depends on a reliable and tested codebase.

Defined in

Dependencies are defined in the following files:

• C#: mahaam.csproj
• Java: build.gradle
• Go: go.mod
• TypeScript: package.json
• Python: pyproject.toml

Examples

C#

// mahaam.csproj file
<ItemGroup>
	<PackageReference Include="Dapper" Version="2.0.123" />
</ItemGroup>

Java

// build.gradle file
dependencies {
    implementation 'org.jdbi:jdbi3-core:3.49.5'
}

Go

// go.mod file
require (
    github.com/gin-gonic/gin v1.10.0
)

TypeScript

// package.json file
"dependencies": {
  "winston": "^3.17.0"
}

Python

# pyproject.toml file
dependencies = [
    "fastapi[standard]>=0.116.0",
]

Registry

Dependencies are stored in these registries for each language:

C#

NuGet Package Gallery
https://www.nuget.org/

Java

Maven Central Repository
https://mvnrepository.com/

Go

Go Module Proxy & Registry
https://pkg.go.dev/

TypeScript

npm Registry
https://www.npmjs.com/

Python

Python Package Index (PyPI)
https://pypi.org/

How to add

To add a dependency:

C#

# Add a package using .NET CLI
dotnet add package Newtonsoft.Json

Java

# Add to build.gradle dependencies block
# Then run gradle build to download
./gradlew build

Go

# Add and download a module
go get github.com/gin-gonic/gin

TypeScript

# Install a package using pnpm
pnpm add winston

Python

# Install a package using uv
uv add fastapi

Version Management

Dependencies version management is done using semantic versioning MAJOR.MINOR.PATCH:

• MAJOR: Breaking changes that require code updates
• MINOR: New features that are backward compatible
• PATCH: Bug fixes that are backward compatible

Version Ranges

^1.2.3 # Compatible with 1.x.x (>=1.2.3 <2.0.0)
~1.2.3 # Compatible with 1.2.x (>=1.2.3 <1.3.0)
1.2.3 # Exact version only

> = 1.2.3 # Greater than or equal to 1.2.3

Best Practices

- Use exact versions for critical dependencies
- Use ^ for minor updates in development
- Pin exact versions in production
- Regular dependency audits for security

Lock Files

Lock files are generated files containing dependency definitions:

• Lock files pin the exact dependency versions.
• Ensures reproducible builds across all environments.
• Should be committed to version control.

C#

# No standard lock file

# Uses PackageReference with exact versions

Java

# No standard lock file

# Gradle uses dependency resolution rules

Go

go.sum

# Contains cryptographic checksums of dependencies

TypeScript

pnpm-lock.yaml

# Generated by pnpm, locks all dependency versions

Python

uv.lock

# Generated by uv, locks all dependency versions

Key Dependencies

These are the key dependencies used in Mahaam across different language implementations:

C#

- Dapper: Lightweight ORM
- Swashbuckle.AspNetCore: Swagger docs
- Newtonsoft.Json: JSON library
- Microsoft.IdentityModel.Tokens: JWT token
- Serilog: Logging framework
- Twilio: Verification service (e.g., SMS/OTP)

Java

- Quarkus REST: HTTP web framework
- Jackson: JSON processing library
- JDBI: Lightweight database client
- SmallRye OpenAPI: Swagger docs
- JJWT: JWT library for authentication
- Twilio: Verification service (e.g., SMS/OTP)

Go

- Gin: HTTP web framework
- SQLx: Database query extensions
- JWT: JSON Web Token implementation
- Zap: Logging library
- Twilio Go: Verification service (e.g., SMS/OTP)

TypeScript

- NestJS: HTTP Web framework
- Postgres (pg): PostgreSQL client
- jsonwebtoken: JWT authentication library
- Winston: Logging library
- Twilio: Verification service (e.g., SMS/OTP)

Python

- FastAPI: HTTP Web framework
- Uvicorn: HTTP server
- SQLAlchemy: SQL toolkit and ORM
- Twilio: Verification service (e.g., SMS/OTP)