# coova/coova-chilli architecture

> Architecture diagram of the GitHub repository coova/coova-chilli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/coova/coova-chilli
- Repository: https://github.com/coova/coova-chilli

## Overview

##### Project Type and Purpose
- CoovaChilli is a monolithic, C-based network access controller that provides a captive-portal / walled-garden environment on a Linux gateway. It intercepts user traffic via netfilter/iptables, runs an embedded DHCP and DNS server, and redirects HTTP requests to a mini-portal for authentication against RADIUS or an HTTP backend.

##### File‐Structure Analysis
- Top‐level directories:
- src/            – core C code (packet I/O, conn tracking, modules: DHCP, DNS, redir, radius, ssl, nat, etc.)
- miniportal/     – templates and scripts for the captive portal UI (CGI, shell wrappers, HTML/TMPL)
- www/            – client-side JavaScript and HTML templates for optional web controller
- conf/           – configuration file templates (chilli.conf, up/down scripts)
- bstring/, json/ – bundled third-party libraries (bstrlib, json-c)
- linux/ under src – netfilter kernel module glue (ipt_coova)
- doc/, INSTALL    – user/developer documentation and build instructions
- distro/, debian/, rpm/ – packaging for various Linux distributions
- Build system: Autotools (configure.ac, Makefile.am, bootstrap).

##### README Insights
- Captive-portal controller using RADIUS or HTTP for auth/accounting
- GPL-licensed, extensible via “sample-mod.c” and module hooks
- Uses standard C libraries plus bundled bstring and json-c

- Linux Host & Network Stack
- Netfilter/Iptables Hook (ipt_coova kernel module)
- Chilli Core (single process)
– Packet Processor & Connection Tracker
– Embedded DHCP Server
– Embedded DNS Resolver/Redirector
– Redirect Engine (HTTP interceptor)
– RADIUS Client Module (src/radius.*)
– SSL/TLS Module (src/mssl, sslSocket)
– Configuration Loader (conf/)
– Logging/Accounting Writer
- Miniportal CGI/Web UI (templates & scripts)
- External Services
– RADIUS Server(s)
– HTTP Auth API (if used)
– Upstream Internet

1. User Device → Ethernet/Wi-Fi → Linux Network Stack
2. Packets hit iptables → sent to CoovaChilli packet processor
3. Unauthenticated clients get DHCP IP, DNS spoof to captive portal
4. HTTP requests → Redirect Engine → miniportal CGI
5. Miniportal → RADIUS Client / HTTP API → External Auth Server → reply
6. On success → Chilli Core updates conn tracking → allows traffic to Upstream
7. Accounting records → written to local file or sent via RADIUS acct

c. Architectural Patterns & Principles
- Modular C code with clear separation of packet I/O, protocol modules, and portal UI
- Embedding third-party libs rather than external dependencies (bstring, json)
- Autotools for portability, distro folders for packaging
- Single process with internal plugin-like modules (via chilli_module.c)

d. Key Technologies & Frameworks
- C, POSIX APIs, Linux netfilter/iptables (libxt_coova)
- Autotools (configure, Makefile.am)
- bstrlib & json-c for string/JSON handling
- Shell & CGI scripts for miniportal
- RADIUS protocol for AAA

##### Essential Details to Capture
- Packet interception and dispatch via netfilter/iptables
- Internal DHCP and DNS for captive-portal enforcement
- HTTP redirect engine pointing to miniportal scripts
- RADIUS/HTTP backend calls for authentication and accounting
- The flow from “unauthenticated” to “authenticated” state in connection tracker

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Kernel Space
    subgraph "Kernel Space"
        KernelHook["Netfilter Hook\n(ipt_coova)"] 
    end

    %% User Space
    subgraph "User Space"
        subgraph "Chilli Core"
            PP["Packet Processor &\nConnection Tracker"] 
            DHCP["Embedded DHCP Server"] 
            DNS["Embedded DNS Resolver/\nRedirector"] 
            REDIR["Redirect Engine\n(HTTP Interceptor)"] 
            RADIUS["RADIUS Client Module"] 
            SSL["SSL/TLS Module"] 
            CONF["Configuration Loader"] 
            LOG["Logging/Accounting Writer"] 
        end
        MINI["Miniportal CGI/Web UI"] 
        LIB1["bstring Library"] 
        LIB2["json-c Library"] 
    end

    %% External Services
    subgraph "External Services"
        RADIUS_SRV["RADIUS Server(s)"] 
        HTTP_API["HTTP Auth API"] 
        INTERNET["Upstream Internet"] 
    end

    %% Data Flows
    User["User Device"] -->|"Ethernet/Wi-Fi"| KernelHook
    KernelHook -->|“Packets”| PP
    PP -->|"DHCP Discover"| DHCP
    PP -->|"DNS Query"| DNS
    DNS -->|"HTTP Redirect"| REDIR
    REDIR -->|"HTTP Request"| MINI
    MINI -->|"RADIUS Access-Request"| RADIUS
    MINI -->|"HTTP Auth Request"| HTTP_API
    RADIUS -->|"Access-Request"| RADIUS_SRV
    RADIUS_SRV -->|"Access-Accept"| RADIUS
    RADIUS -->|"Auth Success"| PP
    PP -->|"Allowed Traffic"| INTERNET
    PP -->|"Accounting"| LOG

    %% Library Dependencies
    RADIUS -->|uses| LIB1
    SSL -->|uses| LIB2

    %% Click Events
    click KernelHook "https://github.com/coova/coova-chilli/blob/master/src/linux/libxt_coova.c"
    click PP "https://github.com/coova/coova-chilli/blob/master/src/pkt.c"
    click DHCP "https://github.com/coova/coova-chilli/blob/master/src/dhcp.c"
    click DNS "https://github.com/coova/coova-chilli/blob/master/src/dns.c"
    click REDIR "https://github.com/coova/coova-chilli/blob/master/src/redir.c"
    click RADIUS "https://github.com/coova/coova-chilli/blob/master/src/radius.c"
    click SSL "https://github.com/coova/coova-chilli/blob/master/src/mssl.c"
    click CONF "https://github.com/coova/coova-chilli/blob/master/conf/chilli.conf.in"
    click LOG "https://github.com/coova/coova-chilli/blob/master/src/msgstat.c"
    click MINI "https://github.com/coova/coova-chilli/tree/master/miniportal/"
    click LIB1 "https://github.com/coova/coova-chilli/blob/master/bstring/bstrlib.c"
    click LIB2 "https://github.com/coova/coova-chilli/blob/master/json/json_object.c"

    %% Styles
    classDef kernel fill:#8FBC8F,stroke:#333,stroke-width:1px
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef ui fill:#FFA500,stroke:#333,stroke-width:1px
    classDef lib fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef ext fill:#DDA0DD,stroke:#333,stroke-width:1px

    class KernelHook kernel
    class PP,SQL,SSl,CONF,LOG core
    class DHCP,DNS,REDIR,RADIUS core
    class SSL core
    class MINI ui
    class LIB1,LIB2 lib
    class RADIUS_SRV,HTTP_API,INTERNET ext
```
