# compdemocracy/polis architecture

> Architecture diagram of the GitHub repository compdemocracy/polis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/compdemocracy/polis
- Repository: https://github.com/compdemocracy/polis

## Overview

a. External Services Integration:
- Authentication systems (social login)
- Translation services
- Email services
- Spam filtering (Akismet)

b. Internal Communication:
- REST API endpoints between clients and server
- WebSocket connections for real-time updates
- Math server communication for analytics processing

##### Key Architectural Patterns

a. Microservices Architecture:
- Clear separation between math, main server, and file server
- Docker container boundaries

b. Data Flow:
- Comment submission flow
- Voting and participation flow
- Analytics processing pipeline
- Report generation flow

##### Infrastructure Components

a. Docker Container Structure:
- Container relationships defined in docker-compose
- Development vs production configurations

b. Networking:
- Port mappings (80/443 for production)
- Internal service communication

##### Specific Implementation Details

a. Technology Stack (Show as annotations):
- Frontend: React, Redux
- Backend: Node.js, TypeScript
- Analytics: Clojure
- Database: PostgreSQL

b. Key Features:
- Real-time processing
- Multi-language support
- Data export capabilities
- Visualization components

##### Security Layer

- SSL/HTTPS endpoints
- Authentication flows
- API security measures
- Database access controls

##### Layering
- Top: Client applications
- Middle: Server components
- Bottom: Database and storage
- Side: External services

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles and Classes
    classDef frontend fill:#3498db,stroke:#2980b9,color:white
    classDef server fill:#2ecc71,stroke:#27ae60,color:white
    classDef database fill:#f1c40f,stroke:#f39c12,color:white
    classDef external fill:#95a5a6,stroke:#7f8c8d,color:white
    classDef security fill:#e74c3c,stroke:#c0392b,color:white

    %% Client Layer
    subgraph Clients
        AdminClient["Admin Client"]:::frontend
        ParticipationClient["Participation Client"]:::frontend
        ReportClient["Report Client"]:::frontend
    end

    %% Server Layer
    subgraph Servers
        MainServer["Main Server\n(Node.js/TypeScript)"]:::server
        MathServer["Math Server\n(Clojure Analytics)"]:::server
        FileServer["File Server\n(Static Assets)"]:::server
    end

    %% Database Layer
    Database[(PostgreSQL)]:::database

    %% External Services
    subgraph External
        Auth["Authentication\nServices"]:::external
        Translation["Translation\nServices"]:::external
        Email["Email\nServices"]:::external
        SpamFilter["Spam Filter\n(Akismet)"]:::external
    end

    %% Security Components
    subgraph Security
        PasswordMgmt["Password\nManagement"]:::security
        SessionMgmt["Session\nManagement"]:::security
        SSL["SSL/HTTPS"]:::security
    end

    %% Connections
    AdminClient --> MainServer
    ParticipationClient --> MainServer
    ReportClient --> MainServer
    MainServer --> Database
    MainServer <--> MathServer
    MainServer --> FileServer
    MainServer <--> Auth
    MainServer <--> Translation
    MainServer <--> Email
    MainServer <--> SpamFilter
    MainServer --> PasswordMgmt
    MainServer --> SessionMgmt
    SSL --> MainServer

    %% Click Events
    click AdminClient "https://github.com/compdemocracy/polis/tree/edge/client-admin/"
    click ParticipationClient "https://github.com/compdemocracy/polis/tree/edge/client-participation/"
    click ReportClient "https://github.com/compdemocracy/polis/tree/edge/client-report/"
    click MainServer "https://github.com/compdemocracy/polis/tree/edge/server/"
    click MathServer "https://github.com/compdemocracy/polis/tree/edge/math/"
    click FileServer "https://github.com/compdemocracy/polis/tree/edge/file-server/"
    click Database "https://github.com/compdemocracy/polis/tree/edge/server/postgres/migrations/"
    click Auth "https://github.com/compdemocracy/polis/tree/edge/server/src/auth/"
    click Email "https://github.com/compdemocracy/polis/tree/edge/server/src/email/"
    click Translation "https://github.com/compdemocracy/polis/tree/edge/client-participation/js/strings/"
    click PasswordMgmt "https://github.com/compdemocracy/polis/blob/edge/server/src/auth/password.ts"
    click SessionMgmt "https://github.com/compdemocracy/polis/blob/edge/server/src/session.ts"

    %% Legend
    subgraph Legend
        Frontend["Frontend Component"]:::frontend
        ServerComp["Server Component"]:::server
        DB["Database"]:::database
        Ext["External Service"]:::external
        Sec["Security Component"]:::security
    end
```
