# Main Modules of the CoSec Framework: Complete Architecture Guide

> Explore the main modules of the CoSec framework including cosec-api, cosec-core, and cosec-jwt. Discover its complete architecture for reactive, multi-tenant, policy-driven security in JVM applications.

- Repository: [Ahoo Wang/cosec](https://github.com/ahoo-wang/cosec)
- Tags: architecture
- Published: 2026-02-23

---

**The CoSec framework comprises 15+ Gradle sub-projects including cosec-api, cosec-core, cosec-jwt, cosec-webmvc, cosec-webflux, and cosec-gateway, delivering a reactive, multi-tenant, policy-driven security solution for JVM applications.**

CoSec is an open-source security framework designed for reactive, multi-tenant applications. Understanding the main modules of the CoSec framework is essential for architects integrating policy-based access control into Spring Boot or Spring Cloud Gateway applications. The project is organized as a multi-module Gradle build where each sub-project addresses a specific cross-cutting concern, from core policy evaluation to OpenTelemetry instrumentation.

## Core Foundation Modules

### cosec-api

The **cosec-api** module defines the public contracts, data classes, and interfaces that all other modules depend upon. It establishes the foundational abstractions for policies, principals, and security contexts without imposing implementation details.

Key file: [`cosec-api/src/main/kotlin/me/ahoo/cosec/api/CoSec.kt`](https://github.com/ahoo-wang/cosec/blob/main/cosec-api/src/main/kotlin/me/ahoo/cosec/api/CoSec.kt)

### cosec-core

The **cosec-core** module contains the engine that drives the framework. It implements policy loading, evaluation logic, condition and action matching, tenant isolation, token handling, and security context management. The `DefaultPolicyEvaluator` class serves as the primary entry point for policy decisions.

Key file: [`cosec-core/src/main/kotlin/me/ahoo/cosec/policy/DefaultPolicyEvaluator.kt`](https://github.com/ahoo-wang/cosec/blob/main/cosec-core/src/main/kotlin/me/ahoo/cosec/policy/DefaultPolicyEvaluator.kt)

## Authentication and Identity Modules

### cosec-jwt

The **cosec-jwt** module provides JWT-based authentication support, handling token generation, parsing, and verification. This module is essential for stateless security architectures.

### cosec-social

The **cosec-social** module integrates third-party identity providers via OAuth2, managing token exchange and social login flows.

## Web Framework Adapters

### cosec-webmvc

For traditional servlet-based applications, the **cosec-webmvc** module provides Spring WebMVC integrations including `HandlerInterceptor` and `Filter` implementations that enforce policies on incoming requests.

### cosec-webflux

The **cosec-webflux** module offers reactive support for Spring WebFlux applications, implementing `WebFilter` to handle non-blocking security checks.

### cosec-gateway

Designed for API gateway architectures, the **cosec-gateway** module implements a Spring Cloud Gateway filter that enforces policies at the edge. The `AuthorizationGatewayFilter` class processes each exchange against configured policies.

Key file: [`cosec-gateway/src/main/kotlin/me/ahoo/cosec/gateway/AuthorizationGatewayFilter.kt`](https://github.com/ahoo-wang/cosec/blob/main/cosec-gateway/src/main/kotlin/me/ahoo/cosec/gateway/AuthorizationGatewayFilter.kt)

## Infrastructure and Utility Modules

### cosec-cocache

The **cosec-cocache** module provides caching abstractions for policies and application-role permissions, including a Redis-backed implementation via `RedisPolicyRepository`.

Key file: [`cosec-cocache/src/main/kotlin/me/ahoo/cosec/cache/RedisPolicyRepository.kt`](https://github.com/ahoo-wang/cosec/blob/main/cosec-cocache/src/main/kotlin/me/ahoo/cosec/cache/RedisPolicyRepository.kt)

### cosec-ip2region

Supporting geo-location-based access control, the **cosec-ip2region** module provides IP-to-region lookup capabilities used by the built-in `IpRegion` condition matcher.

Key file: [`cosec-ip2region/src/main/kotlin/me/ahoo/cosec/ip2region/IpRegionResolver.kt`](https://github.com/ahoo-wang/cosec/blob/main/cosec-ip2region/src/main/kotlin/me/ahoo/cosec/ip2region/IpRegionResolver.kt)

### cosec-opentelemetry

For observability, the **cosec-opentelemetry** module instruments security decisions with OpenTelemetry, extracting identity attributes for distributed tracing via `CoSecAttributesExtractor`.

Key file: [`cosec-opentelemetry/src/main/kotlin/me/ahoo/cosec/opentelemetry/CoSecAttributesExtractor.kt`](https://github.com/ahoo-wang/cosec/blob/main/cosec-opentelemetry/src/main/kotlin/me/ahoo/cosec/opentelemetry/CoSecAttributesExtractor.kt)

### cosec-openapi

The **cosec-openapi** module generates OpenAPI (Swagger) documentation that embeds CoSec policy information, bridging security configuration with API documentation.

## Spring Boot Integration and Dependency Management

### cosec-spring-boot-starter

The **cosec-spring-boot-starter** module provides auto-configuration that wires together the core modules, web adapters, and cache implementations. It parses `cosec-policy/*.json` files and registers the security filter chain automatically.

Key file: [`cosec-spring-boot-starter/src/main/kotlin/me/ahoo/cosec/spring/boot/starter/CoSecAutoConfiguration.kt`](https://github.com/ahoo-wang/cosec/blob/main/cosec-spring-boot-starter/src/main/kotlin/me/ahoo/cosec/spring/boot/starter/CoSecAutoConfiguration.kt)

### cosec-bom and cosec-dependencies

These modules provide **Bill of Materials (BOM)** and dependency management coordinates, allowing consumers to import a single versioned platform definition rather than managing individual module versions.

## Complete Module Enumeration

The root `settings.gradle.kts` confirms the full module structure:

```kotlin
include(":cosec-bom")
include(":cosec-dependencies")
include(":cosec-api")
include(":cosec-core")
include(":cosec-jwt")
include(":cosec-cocache")
include(":cosec-social")
include(":cosec-webmvc")
include(":cosec-webflux")
include(":cosec-spring-boot-starter")
include(":cosec-gateway")
include(":cosec-gateway-server")
include(":cosec-opentelemetry")
include(":cosec-ip2region")
include(":code-coverage-report")
include(":cosec-openapi")

```

## Practical Integration Examples

### Spring Boot Application Setup

Add the starter dependency to your `build.gradle.kts`:

```kotlin
dependencies {
    implementation("me.ahoo.cosec:cosec-spring-boot-starter:2.2.0")
}

```

Configure policy locations in [`application.yml`](https://github.com/ahoo-wang/cosec/blob/main/application.yml):

```yaml
cosec:
  policy:
    locations:
      - classpath:/cosec-policy/*.json

```

Access the security context in a controller:

```kotlin
@RestController
class UserController {
    @GetMapping("/user/{id}")
    fun getUser(@PathVariable id: String, request: ServerHttpRequest): String {
        val ctx = request.getSecurityContext()
        return "Current principal = ${ctx.principal?.id}"
    }
}

```

### Framework-Agnostic Core Usage

For non-Spring applications, use the core API directly:

```kotlin
val configuration = Configuration()
val policyLoader = LocalPolicyLoader(configuration)
val policy = policyLoader.load("classpath:/my-policy.json")

val evaluator = DefaultPolicyEvaluator(configuration)
val request = Request.builder()
    .path("/order/ship")
    .principal(SimplePrincipal("bob"))
    .build()

val result = evaluator.evaluate(request, policy)
println("Allowed? ${result.isAllowed}")

```

## Summary

- **CoSec** is organized as a multi-module Gradle project with over 15 sub-projects.
- **cosec-api** and **cosec-core** provide the foundational contracts and policy evaluation engine.
- **cosec-jwt** and **cosec-social** handle authentication via tokens and OAuth2.
- **cosec-webmvc**, **cosec-webflux**, and **cosec-gateway** adapt the framework to specific runtime environments.
- **cosec-spring-boot-starter** automates configuration for Spring Boot applications.
- Supporting modules like **cosec-cocache**, **cosec-ip2region**, **cosec-opentelemetry**, and **cosec-openapi** provide caching, geo-location, observability, and documentation capabilities.

## Frequently Asked Questions

### What is the minimum set of CoSec modules required for a Spring Boot application?

For a standard Spring Boot web application, you only need the **cosec-spring-boot-starter** module. This starter transitively pulls in **cosec-api**, **cosec-core**, and the appropriate web adapter (**cosec-webmvc** or **cosec-webflux**) based on your classpath. You can add **cosec-jwt** or **cosec-cocache** as needed for token handling or distributed caching.

### How does CoSec support reactive programming models?

CoSec provides dedicated adapters for reactive stacks. The **cosec-webflux** module implements `WebFilter` for Spring WebFlux applications, while **cosec-gateway** provides a `GatewayFilter` for Spring Cloud Gateway. Both adapters use the same **cosec-core** evaluation engine, ensuring consistent policy enforcement across blocking and non-blocking architectures.

### Can CoSec be used without Spring Framework?

Yes. The **cosec-api** and **cosec-core** modules are framework-agnostic Kotlin libraries. You can instantiate `DefaultPolicyEvaluator` and `LocalPolicyLoader` directly, load JSON policy files, and evaluate requests programmatically. The Spring-specific modules (webmvc, webflux, starter) are optional adapters that simplify integration for Spring ecosystems.

### Where are policy definitions stored in a CoSec application?

By default, policies are loaded from JSON files located in `classpath:/cosec-policy/`. The **cosec-spring-boot-starter** automatically scans this location. For distributed deployments, the **cosec-cocache** module provides a `RedisPolicyRepository` that stores policies in Redis, enabling centralized policy management across multiple service instances.