# nimbusscale/dominant-species architecture

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

- Interactive diagram: https://gitdiagram.com/nimbusscale/dominant-species
- Repository: https://github.com/nimbusscale/dominant-species

## Overview

##### Main Components

a. Frontend Layer:
- Angular Application (packages/frontend)
- Game Components
- Authentication Components
- State Management Services
- Game Logic Services

b. Backend Layer:
- API Gateway
- Lambda Functions (packages/backend)
- API Handler
- Auth Handler
- WebSocket Handler
- Signup Handler

c. AWS Services:
- Cognito User Pool (Authentication)
- DynamoDB Tables
- S3 Buckets (State and Website storage)
- IAM Roles and Policies

**[Client Layer]**
- ↕
**[API Layer]**
- ↕
**[Infrastructure Layer]**

##### Component Relationships

- Frontend components → API Gateway
- API Gateway → Lambda Functions
- Lambda Functions → DynamoDB/S3
- Authentication flow through Cognito
- WebSocket connections for real-time game state updates

##### Detailed Component Breakdown

Frontend (Angular):
**[Game Components] → [State Management] → [API Services]**
- ↓                    ↓
**[Auth Components] → [Game Logic Services]**

Backend (Lambda):
**[API Handler] → [Game State Manager]**
- ↓              ↓
**[Auth Handler] → [Database Managers]**

Infrastructure:
**[Cognito] → [IAM Roles]**
- ↓          ↓
**[DynamoDB] ← [Lambda]**
- ↓
**[S3 Buckets]**

##### Additional Elements

- Version information
- Scaling capabilities
- Security boundaries

##### Implementation Notes

- Keep component sizes proportional to their complexity
- Annotations for critical paths

- The microservices architecture
- The game state management flow
- Real-time communication paths
- Security boundaries and authentication flow
- Data persistence strategy

Remember to include deployment workflows from the .github/workflows directory, showing how the CI/CD pipeline fits into the overall architecture.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles
    classDef frontend fill:#3498db,stroke:#2980b9,color:white
    classDef backend fill:#2ecc71,stroke:#27ae60,color:white
    classDef aws fill:#e67e22,stroke:#d35400,color:white
    classDef database fill:#9b59b6,stroke:#8e44ad,color:white
    classDef auth fill:#f1c40f,stroke:#f39c12,color:black
    
    %% Frontend Layer
    subgraph Frontend
        MainApp["Angular App"]:::frontend
        GameComp["Game Components"]:::frontend
        AuthComp["Auth Components"]:::frontend
        StateManage["State Management"]:::frontend
        GameLogic["Game Logic"]:::frontend
        FrontAuth["Frontend Auth"]:::frontend
    end

    %% Backend Layer
    subgraph Backend
        APIHandler["API Handler"]:::backend
        AuthHandler["Auth Handler"]:::backend
        WSHandler["WebSocket Handler"]:::backend
        SignupHandler["Signup Handler"]:::backend
        DBManage["Database Management"]:::backend
        BackAuth["Backend Auth"]:::backend
        GameState["Game State Manager"]:::backend
    end

    %% AWS Infrastructure
    subgraph AWS
        APIGateway["API Gateway"]:::aws
        Cognito["Cognito User Pool"]:::aws
        DynamoDB["DynamoDB Tables"]:::database
        S3State["State Bucket"]:::database
        S3Web["Website Bucket"]:::database
        IAMRoles["IAM Roles"]:::aws
    end

    %% Relationships
    MainApp --> GameComp
    MainApp --> AuthComp
    GameComp --> StateManage
    GameComp --> GameLogic
    AuthComp --> FrontAuth
    StateManage --> APIGateway
    FrontAuth --> Cognito

    APIGateway --> APIHandler
    APIGateway --> AuthHandler
    APIGateway --> WSHandler
    APIGateway --> SignupHandler

    AuthHandler --> Cognito
    AuthHandler --> BackAuth
    SignupHandler --> Cognito
    
    APIHandler --> GameState
    WSHandler --> GameState
    GameState --> DBManage
    DBManage --> DynamoDB
    DBManage --> S3State
    
    Cognito --> IAMRoles
    IAMRoles --> DynamoDB
    IAMRoles --> S3State
    IAMRoles --> S3Web

    %% Click Events
    click MainApp "https://github.com/nimbusscale/dominant-species/tree/main/packages/frontend/src/app"
    click GameComp "https://github.com/nimbusscale/dominant-species/tree/main/packages/frontend/src/app/game/component"
    click AuthComp "https://github.com/nimbusscale/dominant-species/tree/main/packages/frontend/src/app/engine/component/login-page"
    click StateManage "https://github.com/nimbusscale/dominant-species/tree/main/packages/frontend/src/app/engine/service/game-state"
    click GameLogic "https://github.com/nimbusscale/dominant-species/tree/main/packages/frontend/src/app/game/service"
    click FrontAuth "https://github.com/nimbusscale/dominant-species/tree/main/packages/frontend/src/app/engine/service/auth"
    
    click APIHandler "https://github.com/nimbusscale/dominant-species/blob/main/packages/backend/src/api-handler.ts"
    click AuthHandler "https://github.com/nimbusscale/dominant-species/blob/main/packages/backend/src/auth-handler.ts"
    click WSHandler "https://github.com/nimbusscale/dominant-species/blob/main/packages/backend/src/ws-handler.ts"
    click SignupHandler "https://github.com/nimbusscale/dominant-species/blob/main/packages/backend/src/signup-handler.ts"
    click DBManage "https://github.com/nimbusscale/dominant-species/tree/main/packages/backend/src/lib/db"
    click BackAuth "https://github.com/nimbusscale/dominant-species/blob/main/packages/backend/src/lib/auth.ts"
    click GameState "https://github.com/nimbusscale/dominant-species/blob/main/packages/backend/src/lib/state/game-state-object-manager.ts"
    
    click Cognito "https://github.com/nimbusscale/dominant-species/blob/main/packages/infra/src/lib/user-pool-stack.ts"
    click DynamoDB "https://github.com/nimbusscale/dominant-species/blob/main/packages/infra/src/lib/vpa-game-table-stack.ts"
    click S3State "https://github.com/nimbusscale/dominant-species/blob/main/packages/infra/src/lib/state-bucket-stack.ts"
    click S3Web "https://github.com/nimbusscale/dominant-species/blob/main/packages/infra/src/lib/website-bucket-stack.ts"
    click IAMRoles "https://github.com/nimbusscale/dominant-species/blob/main/packages/infra/src/lib/iam-stack.ts"
```
