# momosecurity/aswan architecture

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

- Interactive diagram: https://gitdiagram.com/momosecurity/aswan
- Repository: https://github.com/momosecurity/aswan

## Overview

Based on our analysis of the file tree and README, this project is a full‐stack risk control engine with both API and web management components. It is designed to control (or “risk‐manage”) user actions by evaluating a set of strategies (such as black/white/grey lists, boolean rules, frequency limits, etc.) and then either passing or denying requests. The backend risk logic is implemented using Python modules (for risk models, built-in functions, etc.) while the administrative interfaces and configuration pages are built on Django (found in the “www” folder). There are also dedicated clients for interacting with backend storage such as MySQL, MongoDB, and Redis, plus separate configuration and logging modules.

- API / Risk Server: Represent the risk engine that exposes two main services – a query interface (to check risk and control flow) and a report interface (for logging events), as implemented in risk_server.py.
- Business Logic Modules:
– Risk Models (in the “risk_models” folder) which contain core logic for evaluating various risk strategies.
– Built-in Functions (in “builtin_funcs”) which allow extension for custom checks (e.g., “is_abnormal”, “user_login_count”).
- Web Administration Interface: The Django-powered backend (in the “www” folder) that includes modules for rules, permissions, management of user and risk control configurations.
- Configuration: A separate configuration layer (from “config” and “www/settings”) that defines environment-specific settings using the RISK_ENV variable.
- Logging: A dedicated logging component (see “log” directory) that handles logging and storage of risk-related events.
- Deployment & Infrastructure: Indicate the Docker and docker-compose setups included in the “deploy” directory that package different components (e.g., separate Dockerfiles for backend, service, task processes).

- That the business logic modules interact with the Data Clients to access Redis (for caching or counters), MySQL (for persistent data like risk rules, user logs, etc.), and MongoDB (for storing semi-structured data if required).
- Logging module receiving data from various parts of the system (risk server, business logic) for audit purposes.
- Optionally, show an infrastructure layer (Docker Compose, deployment configurations) that orchestrates these services and may include a load balancer (e.g., nginx) in production.

##### Important Architectural Patterns
- Separation of Concerns – Clearly demarcate the division between the risk evaluation (API) and the administrative dashboard (Django web app).
- Modular Design – Each folder (risk_models, builtin_funcs, clients, config) is an independent module that can be maintained separately.
- Environment-based Configuration – The use of RISK_ENV to differentiate between development, testing, and production environments.
- Data Flow Pattern – A typical flow might be: a business system calls the API → risk server queries risk_models (using builtin_funcs) → database clients are used → results (and logs) are processed and possibly reported to the logging module.

##### Relevant Technologies, Frameworks, or Libraries
- Python 3.7+ as the development language.
- Django for the web/admin interface (inside the “www” directory).
- Docker and Docker Compose for deployment.
- Database systems: MySQL, MongoDB, and Redis.
- Use of built-in Python modules for logging, error handling, and testing (see “tests” directory).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    EC["External Clients"]:::external

    %% API Risk Engine
    subgraph "API Risk Engine"
        RS["Risk Server (API)"]:::api
    end

    %% Business Logic Modules
    subgraph "Business Logic Modules"
        RM["Risk Models"]:::business
        BF["Built-in Functions"]:::business
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        DC["Data Clients (MySQL, MongoDB, Redis)"]:::persistence
    end

    %% Administration & Configuration
    subgraph "Administration & Config"
        WA["Django Web Admin Interface"]:::web
        CF["Configuration Module"]:::config
    end

    %% Logging Module
    LM["Logging Module"]:::log

    %% Deployment & Infrastructure
    DI["Deployment & Infrastructure"]:::deploy

    %% Data Flow Arrows
    EC -->|"query/report"| RS
    RS -->|"evaluate"| RM
    RS -->|"custom-checks"| BF
    RM -->|"data-access"| DC
    BF -->|"data-access"| DC
    RS -->|"logs"| LM
    RM -->|"logs"| LM
    BF -->|"logs"| LM
    WA -->|"admin-access"| DC
    WA -->|"loads-config"| CF

    %% Deployment orchestrates services
    DI -->|"orchestrates"| RS
    DI -->|"orchestrates"| WA
    DI -->|"orchestrates"| DC
    DI -->|"orchestrates"| LM
    DI -->|"orchestrates"| CF

    %% Click Events
    click RS "https://github.com/momosecurity/aswan/blob/master/risk_server.py"
    click RM "https://github.com/momosecurity/aswan/tree/master/risk_models/"
    click BF "https://github.com/momosecurity/aswan/tree/master/builtin_funcs/"
    click DC "https://github.com/momosecurity/aswan/tree/master/clients/"
    click WA "https://github.com/momosecurity/aswan/tree/master/www/"
    click CF "https://github.com/momosecurity/aswan/tree/master/config/"
    click LM "https://github.com/momosecurity/aswan/tree/master/log/"
    click DI "https://github.com/momosecurity/aswan/tree/master/deploy/"

    %% Styles
    classDef api fill:#ffcccc,stroke:#d33,stroke-width:2px;
    classDef business fill:#ccffcc,stroke:#090,stroke-width:2px;
    classDef persistence fill:#cce5ff,stroke:#339,stroke-width:2px;
    classDef web fill:#fff2cc,stroke:#993,stroke-width:2px;
    classDef config fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef log fill:#d6eaf8,stroke:#3498db,stroke-width:2px;
    classDef deploy fill:#f5b7b1,stroke:#e74c3c,stroke-width:2px;
    classDef external fill:#fcf3cf,stroke:#f1c40f,stroke-width:2px;
```
