# carvilsi/pwyll architecture

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

- Interactive diagram: https://gitdiagram.com/carvilsi/pwyll
- Repository: https://github.com/carvilsi/pwyll

## Overview

##### Main Components Identification
The system consists of these primary components:
- REST API Server (Node.js)
- MongoDB Database
- Client Interface (separate pwyll-cli project)
- Docker Container Environment

##### Key Architectural Elements
The project follows a typical Node.js backend architecture with:
- Controller Layer (/src/controllers)
- Routes Layer (/src/routes)
- Database Layer (/src/db)
- Error Handling Layer (/src/errorHandlers)
- Utility Services (/src/util)

##### External Client Layer
- Pwyll-cli as an external component
- To API Server with REST API calls

##### API Server Layer (Main Application)
- Routes (snippets, users, infoapp)
- Controllers (snippets_controller, users_controller)
- Error Handlers
- Clear separation of concerns

##### Database Layer
- MongoDB instance
- Persistent volume connection for Docker deployment

##### Security Layer
- Security.ts utility
- Interaction with routes and controllers

##### Client → API Server
- REST API calls for CRUD operations
- User authentication flows

##### Internal Flow
- Routes → Controllers → Database
- Error handling flow paths
- Security middleware integration points

C. Infrastructure Components:
##### Docker Container Environment
- Container boundaries
- Volume mounts for persistence
- Network isolation

Use these specific visual elements:
- Rectangles: Core services
- Hexagons: External interfaces
- Diamonds: Decision points/middleware

- Blue: API components
- Green: Database related
- Yellow: Security components
- Gray: Infrastructure/Docker
- Red: Error handling

##### Test infrastructure integration

Level of Detail:
- Keep high-level architecture clear while showing important implementation details
- Main file references from the source code
- Configuration flow from config directory
- Test coverage scope

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Client
        CLI[pwyll-cli]
    end

    subgraph "API Server"
        subgraph "Routes Layer"
            SR["Snippets Routes"]:::routes
            UR["Users Routes"]:::routes
            IR["Info Routes"]:::routes
        end

        subgraph "Controllers Layer"
            SC["Snippets Controller"]:::controller
            UC["Users Controller"]:::controller
        end

        subgraph "Error Handling"
            EH["Error Handler"]:::error
        end

        subgraph "Security"
            SEC["Security Utility"]:::security
        end

        subgraph "Database Layer"
            DBC["MongoDB Connection"]:::db
        end
    end

    subgraph "Infrastructure"
        subgraph "Docker Environment"
            DF["Dockerfile"]:::docker
            DC_DEV["Dev Docker Compose"]:::docker
            DC_PROD["Prod Docker Compose"]:::docker
        end

        subgraph "Configuration"
            CONF_DEF["Default Config"]:::config
            CONF_PROD["Production Config"]:::config
            CONF_TEST["Test Config"]:::config
        end

        subgraph "Testing"
            TEST_SNIP["Snippet Tests"]:::test
            TEST_USER["User Tests"]:::test
            TEST_SEC["Security Tests"]:::test
        end
    end

    DB[(MongoDB)]:::db

    %% Relationships
    CLI --> SR & UR & IR
    SR & UR & IR --> SC & UC
    SC & UC --> DBC
    DBC --> DB
    SEC -.-> SR & UR & IR
    EH -.-> SR & UR & IR

    %% Click Events
    click SR "https://github.com/carvilsi/pwyll/blob/develop/src/routes/snippets.ts"
    click UR "https://github.com/carvilsi/pwyll/blob/develop/src/routes/users.ts"
    click IR "https://github.com/carvilsi/pwyll/blob/develop/src/routes/infoapp.ts"
    click SC "https://github.com/carvilsi/pwyll/blob/develop/src/controllers/snippets_controller.ts"
    click UC "https://github.com/carvilsi/pwyll/blob/develop/src/controllers/users_controller.ts"
    click EH "https://github.com/carvilsi/pwyll/blob/develop/src/errorHandlers/index.ts"
    click SEC "https://github.com/carvilsi/pwyll/blob/develop/src/util/security.ts"
    click DBC "https://github.com/carvilsi/pwyll/blob/develop/src/db/mongo.ts"
    click DF "https://github.com/carvilsi/pwyll/tree/develop/Dockerfile"
    click DC_DEV "https://github.com/carvilsi/pwyll/blob/develop/devops/dev/docker-compose.yml"
    click DC_PROD "https://github.com/carvilsi/pwyll/blob/develop/devops/docker-compose.yml"
    click CONF_DEF "https://github.com/carvilsi/pwyll/blob/develop/config/default.js"
    click CONF_PROD "https://github.com/carvilsi/pwyll/blob/develop/config/production.js"
    click CONF_TEST "https://github.com/carvilsi/pwyll/blob/develop/config/tests.js"
    click TEST_SNIP "https://github.com/carvilsi/pwyll/tree/develop/test"
    click TEST_USER "https://github.com/carvilsi/pwyll/blob/develop/test/users.test.ts"
    click TEST_SEC "https://github.com/carvilsi/pwyll/blob/develop/test/security.test.ts"

    %% Styling
    classDef routes fill:#3498db
    classDef controller fill:#2ecc71
    classDef error fill:#e74c3c
    classDef security fill:#f1c40f
    classDef db fill:#34495e
    classDef docker fill:#95a5a6
    classDef config fill:#9b59b6
    classDef test fill:#e67e22

    %% Legend
    subgraph Legend
        L1[Routes]:::routes
        L2[Controllers]:::controller
        L3[Error Handling]:::error
        L4[Security]:::security
        L5[Database]:::db
        L6[Docker]:::docker
        L7[Config]:::config
        L8[Testing]:::test
    end
```
