How doumiri-ali/geni works
Purpose and Product Entry Points
Geni is a Kotlin/Spring modular-monolith platform for composing AI-native, industry-specific management products. A selected product is built from platform code, required modules, reusable features, and one vertical; excluded modules are absent from the classpath and artifact. The current shippable entry point is products/clinic/src/main/kotlin/africa/agi/geni/product/clinic/GeniClinicApplication.kt, composed through products/clinic/build-manifest.yaml and products/clinic/build.gradle.kts.
Build-Time Product Composition
Gradle selects a product via -Pgeni.product, enforcing build-time module exclusion rather than runtime feature flags. Modules declare metadata/dependencies in module.yaml; product manifests determine the graph. Architecture rules guard this boundary in platform/architecture-tests/src/test/kotlin/africa/agi/geni/arch/ArchitectureFitnessTest.kt. Core build roots are settings.gradle.kts and build.gradle.kts.
Kernel: Stable Mechanisms and Contracts
platform/kernel is module-independent infrastructure: it declares cross-module ports, annotations, audit integrity types, request pipeline mechanics, tenancy enforcement, module ordering, and migration execution. It must not depend on business modules. Principal boundaries are platform/kernel/src/main/kotlin/africa/agi/geni/kernel/api/KernelPorts.kt, platform/kernel/src/main/kotlin/africa/agi/geni/kernel/registry/ModuleOrder.kt, and platform/kernel/src/main/kotlin/africa/agi/geni/kernel/persistence/migration/ModuleMigrationRunner.kt.
Request, Identity, Authorization, and Tenancy
HTTP requests enter Spring security and a kernel filter pipeline. Tenant binding establishes tenant context before application work; clearing prevents context leakage. Base supplies authentication, principal resolution, and ABAC policy decisions, exposing business-facing ports while adapters implement REST and persistence. Relevant paths: platform/kernel/src/main/kotlin/africa/agi/geni/kernel/pipeline/RequestPipelineConfiguration.kt, platform/kernel/src/main/kotlin/africa/agi/geni/kernel/pipeline/TenantBindingFilter.kt, modules/base/src/main/kotlin/africa/agi/geni/base/application/PolicyDecisionPointImpl.kt.
Data, Isolation, and Audit
PostgreSQL is the primary persistence runtime, provisioned locally through docker-compose.yml and deploy/postgres/init/01-roles.sh. Tenant-aware datasource/context mechanisms form the database chokepoint; base migrations establish identity, policies, settings, licensing, row-level security, and append-only audit. Each module owns versioned migrations. Key paths: platform/kernel/src/main/kotlin/africa/agi/geni/kernel/persistence/TenantAwareDataSource.kt, modules/base/src/main/resources/db/migration/base/V2__rls_and_append_only_audit.sql, modules/accounting/src/main/resources/db/migration/accounting/V1__baseline.sql.
Functional Modules and Verticalization
modules/base is required operational foundation: companies, users, login, audit, policies, licensing, i18n, and persistence adapters. Reusable feature modules such as accounting expose ports rather than direct internals. verticals/clinic contributes clinic-specific composition and UI translation resources; it is included only by its product. Representative paths: modules/base/src/main/kotlin/africa/agi/geni/base/BaseModule.kt, modules/accounting/src/main/kotlin/africa/agi/geni/accounting/api/AccountingPorts.kt, verticals/clinic/src/main/kotlin/africa/agi/geni/vertical/clinic/ClinicModule.kt.
Web and AI Boundaries
The optional web module provides the public shell/security configuration and static entry document; modules and verticals contribute French-first frontend i18n resources. AI is separated into orchestration, proposal, and cloud-client modules, with ports defining model/provider boundaries; implementations are still scaffold-level. Paths: modules/web/src/main/kotlin/africa/agi/geni/web/PublicShellSecurityConfiguration.kt, modules/ai-orchestrator/src/main/kotlin/africa/agi/geni/ai/orchestrator/OrchestratorPorts.kt, modules/ai-proposals/src/main/kotlin/africa/agi/geni/ai/proposals/ProposalPorts.kt.
Components 21
Product build
Build-time composition excludes unselected modules.
- Gradle build roots · Selects a product through -Pgeni.product.
settings.gradle.kts - Architecture fitness rules · Guards module dependency boundaries.
platform/architecture-tests/src/test/kotlin/africa/agi/geni/arch/ArchitectureFitnessTest.kt
Runtime foundation
Kernel mechanisms and base operational services.
- Kernel ports · Stable contracts for module-independent mechanisms.
platform/kernel/src/main/kotlin/africa/agi/geni/kernel/api/KernelPorts.kt - Module ordering
platform/kernel/src/main/kotlin/africa/agi/geni/kernel/registry/ModuleOrder.kt - Request pipeline · Runs security and tenant binding before application work.
platform/kernel/src/main/kotlin/africa/agi/geni/kernel/pipeline/RequestPipelineConfiguration.kt - Tenant binding filter · Binds and clears tenant context per request.
platform/kernel/src/main/kotlin/africa/agi/geni/kernel/pipeline/TenantBindingFilter.kt - Base module · Provides identity, policies, audit, licensing, and persistence adapters.
modules/base/src/main/kotlin/africa/agi/geni/base/BaseModule.kt - Policy decision point
modules/base/src/main/kotlin/africa/agi/geni/base/application/PolicyDecisionPointImpl.kt
Clinic product
Current shippable product assembly.
- Clinic manifest · Defines the clinic product module graph.
products/clinic/build-manifest.yaml - Clinic build
products/clinic/build.gradle.kts - Clinic application · Shippable clinic runtime entry point.
products/clinic/src/main/kotlin/africa/agi/geni/product/clinic/GeniClinicApplication.kt
Optional capabilities
Feature, web, vertical, and AI module boundaries.
- Accounting ports · Reusable accounting boundary.
modules/accounting/src/main/kotlin/africa/agi/geni/accounting/api/AccountingPorts.kt - Clinic vertical · Clinic-specific composition and UI translations.
verticals/clinic/src/main/kotlin/africa/agi/geni/vertical/clinic/ClinicModule.kt - Web public shell · Provides public shell and security configuration.
modules/web/src/main/kotlin/africa/agi/geni/web/PublicShellSecurityConfiguration.kt - AI orchestrator ports · Separates orchestration from model providers.
modules/ai-orchestrator/src/main/kotlin/africa/agi/geni/ai/orchestrator/OrchestratorPorts.kt - AI proposal ports · Defines proposal-generation boundary.
modules/ai-proposals/src/main/kotlin/africa/agi/geni/ai/proposals/ProposalPorts.kt
Persistence
Tenant-isolated PostgreSQL and module migrations.
- Tenant-aware datasource · Applies tenant isolation to database access.
platform/kernel/src/main/kotlin/africa/agi/geni/kernel/persistence/TenantAwareDataSource.kt - Migration runner · Executes ordered module migrations.
platform/kernel/src/main/kotlin/africa/agi/geni/kernel/persistence/migration/ModuleMigrationRunner.kt - PostgreSQL · Primary tenant-isolated persistence store.
docker-compose.yml - Base RLS and audit migration · Establishes row-level security and append-only audit.
modules/base/src/main/resources/db/migration/base/V2__rls_and_append_only_audit.sql - Accounting baseline migration
modules/accounting/src/main/resources/db/migration/accounting/V1__baseline.sql
Connections 22
- Gradle build roots → Clinic build: selects product
- Clinic manifest → Clinic build: composes
- Clinic build → Clinic application: builds
- Architecture fitness rules → Gradle build roots: guards boundaries
- Clinic manifest → Base module: includes
- Clinic manifest → Clinic vertical: includes
- Clinic manifest → Web public shell: optionally includes
- Clinic application → Request pipeline: serves requests through
- Request pipeline → Tenant binding filter: applies
- Tenant binding filter → Tenant-aware datasource: establishes context for
- Web public shell → Request pipeline: configures public security
- Base module → Policy decision point: provides
- Base module → Kernel ports: implements contracts
- Accounting ports → Kernel ports: uses contracts
- Clinic vertical → Base module: builds on
- AI orchestrator ports → AI proposal ports: orchestrates proposals
- Module ordering → Migration runner: orders modules
- Migration runner → Base RLS and audit migration: executes
- Migration runner → Accounting baseline migration: executes when included
- Base RLS and audit migration → PostgreSQL: creates RLS and audit schema
- Accounting baseline migration → PostgreSQL: creates accounting schema
- Tenant-aware datasource → PostgreSQL: connects with tenant isolation