# raystack/frontier architecture

> Architecture diagram of the GitHub repository raystack/frontier, 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/raystack/frontier
- Repository: https://github.com/raystack/frontier

## Overview

##### Main Components Overview

a. Client Interface Layer:
- HTTP/gRPC API Gateway
- CLI Interface
- React-based Admin UI (found in /ui directory)
- JavaScript SDK (found in /sdks/js)

b. Core Services Layer:
- Authentication Service (core/authenticate)
- Authorization Service (core/policy, core/permission)
- Organization Management (core/organization)
- User Management (core/user)
- Project Management (core/project)
- Billing Management (billing/*)
- Audit Service (core/audit)
- Event Service (core/event)

c. Storage Layer:
- PostgreSQL Database (internal/store/postgres)
- SpiceDB (internal/store/spicedb)
- Blob Storage (internal/store/blob)

##### Interaction Flows

a. External Interactions:
- Client requests → API Gateway
- Authentication flows with external IDPs
- Billing integration with payment providers

b. Internal Flows:
- Authentication → Authorization
- Event publishing between services
- Audit logging flows
- Data persistence flows

##### Key Architectural Patterns

- Service-oriented architecture with clear domain boundaries
- Event-driven communication between services
- Repository pattern for data access
- Middleware chain for request processing

##### Component Details
For each major component, include:

- Service name
- Key responsibilities
- External dependencies
- API endpoints (if applicable)

##### Specific Implementation Notes
Important implementation details:

- Authentication strategies (Email OTP, Social Login, API keys, JWT)
- Role-based access control flow
- Billing and subscription management
- Audit logging mechanism

##### Cross-Cutting Concerns
How these aspects interact with all components:

- Configuration management
- Error handling
- Logging
- Metrics collection

Remember to emphasize the multi-tenant nature of the system and how organization/project boundaries are maintained throughout the architecture. This is particularly important given Frontier's role as an identity and access management tool serving multiple organizations and projects.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles
    classDef frontend fill:#a8d1ff,stroke:#333
    classDef core fill:#ff9e9e,stroke:#333
    classDef storage fill:#ffd700,stroke:#333
    classDef utility fill:#98FB98,stroke:#333
    classDef api fill:#DDA0DD,stroke:#333

    %% Client Interface Layer
    subgraph ClientLayer["Client Interface Layer"]
        UI["React Admin UI"]
        SDK["JavaScript SDK"]
        CLI["CLI Interface"]
        API["API Gateway"]
    end

    %% Core Services Layer
    subgraph CoreLayer["Core Services Layer"]
        Auth["Authentication Service"]
        AuthZ["Authorization Service"]
        OrgMgmt["Organization Management"]
        UserMgmt["User Management"]
        ProjMgmt["Project Management"]
        BillMgmt["Billing Management"]
        AuditSvc["Audit Service"]
        EventSvc["Event Service"]
        GroupMgmt["Group Management"]
        RoleMgmt["Role Management"]
        ServiceUser["Service User Management"]
        Invite["Invitation System"]
        Webhook["Webhook System"]
        Domain["Domain Management"]
    end

    %% Storage Layer
    subgraph StorageLayer["Storage Layer"]
        Postgres[(PostgreSQL)]
        SpiceDB[(SpiceDB)]
        BlobStore[(Blob Storage)]
    end

    %% Utility Components
    subgraph UtilityLayer["Utility Components"]
        Logger["Logger"]
        Mailer["Mailer"]
        HTTPUtil["HTTP Utilities"]
        DBUtil["Database Utilities"]
        Config["Configuration"]
    end

    %% Relationships
    UI --> API
    SDK --> API
    CLI --> API
    
    API --> Auth
    API --> AuthZ
    API --> OrgMgmt
    API --> UserMgmt
    API --> ProjMgmt
    API --> BillMgmt
    
    Auth --> EventSvc
    AuthZ --> EventSvc
    OrgMgmt --> EventSvc
    UserMgmt --> EventSvc
    
    EventSvc --> AuditSvc
    
    Auth --> Postgres
    AuthZ --> SpiceDB
    OrgMgmt --> Postgres
    UserMgmt --> Postgres
    ProjMgmt --> Postgres
    BillMgmt --> Postgres
    
    GroupMgmt --> Postgres
    RoleMgmt --> SpiceDB
    ServiceUser --> Postgres
    Invite --> Postgres
    Webhook --> Postgres
    Domain --> Postgres

    %% Click Events
    click UI "https://github.com/raystack/frontier/tree/main/ui/"
    click SDK "https://github.com/raystack/frontier/tree/main/sdks/js/"
    click CLI "https://github.com/raystack/frontier/tree/main/cmd/"
    click API "https://github.com/raystack/frontier/tree/main/internal/api/v1beta1/"
    click Auth "https://github.com/raystack/frontier/tree/main/core/authenticate/"
    click AuthZ "https://github.com/raystack/frontier/tree/main/core/policy/"
    click OrgMgmt "https://github.com/raystack/frontier/tree/main/core/organization/"
    click UserMgmt "https://github.com/raystack/frontier/tree/main/core/user/"
    click ProjMgmt "https://github.com/raystack/frontier/tree/main/core/project/"
    click BillMgmt "https://github.com/raystack/frontier/tree/main/billing/"
    click AuditSvc "https://github.com/raystack/frontier/tree/main/core/audit/"
    click EventSvc "https://github.com/raystack/frontier/tree/main/core/event/"
    click GroupMgmt "https://github.com/raystack/frontier/tree/main/core/group/"
    click RoleMgmt "https://github.com/raystack/frontier/tree/main/core/role/"
    click ServiceUser "https://github.com/raystack/frontier/tree/main/core/serviceuser/"
    click Invite "https://github.com/raystack/frontier/tree/main/core/invitation/"
    click Webhook "https://github.com/raystack/frontier/tree/main/core/webhook/"
    click Domain "https://github.com/raystack/frontier/tree/main/core/domain/"
    click Postgres "https://github.com/raystack/frontier/tree/main/internal/store/postgres/"
    click SpiceDB "https://github.com/raystack/frontier/tree/main/internal/store/spicedb/"
    click BlobStore "https://github.com/raystack/frontier/tree/main/internal/store/blob/"
    click Config "https://github.com/raystack/frontier/tree/main/config/"
    click Logger "https://github.com/raystack/frontier/tree/main/pkg/logger/"
    click Mailer "https://github.com/raystack/frontier/tree/main/pkg/mailer/"
    click HTTPUtil "https://github.com/raystack/frontier/tree/main/pkg/httputil/"
    click DBUtil "https://github.com/raystack/frontier/tree/main/pkg/db/"

    %% Style Applications
    class UI,SDK frontend
    class Auth,AuthZ,OrgMgmt,UserMgmt,ProjMgmt,BillMgmt,AuditSvc,EventSvc,GroupMgmt,RoleMgmt,ServiceUser,Invite,Webhook,Domain core
    class Postgres,SpiceDB,BlobStore storage
    class Logger,Mailer,HTTPUtil,DBUtil,Config utility
    class API api
```
