# karansinghgit/feems architecture

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

- Interactive diagram: https://gitdiagram.com/karansinghgit/feems
- Repository: https://github.com/karansinghgit/feems

## Overview

##### Project Type and Purpose
- This is a full-stack billing management application (“feeMS”) consisting of:
– A Go backend service using Encore to expose RESTful APIs and provision infrastructure
– Temporal workflows to orchestrate durable bill state and business logic
– A Postgres database for persistent storage of bills and line items
– A React/TypeScript frontend for user interaction

##### File Structure
- Top level
– .gitignore, README.md, go.mod/go.sum, encore.app (Encore configuration)
– scripts/ (startup + test helper scripts)
- services/fees/
– service.go (Encore API endpoints)
– workflow.go (Temporal workflow definition with signal/query handlers)
– activities.go (Temporal activities performing DB side effects)
– types.go (shared request/response/workflow payloads)
– migrations/ (Postgres schema versioned SQL files)
– *_test.go (integration and workflow replay tests)
- frontend/
– package.json/tsconfig.json, public/ (static HTML/manifest)
– src/ (React app entrypoints, components, API client)

##### Extract README Insights
- API Layer: Encore exposes REST endpoints for bill lifecycle operations
- Workflow Layer: Temporal workflows maintain per-bill state and handle signals (add item, close bill)
- Activities: Execute side-effects against Postgres (create/update bills & line items)
- Database: Postgres via Encore’s sqldb abstraction
- Frontend: Thin React app communicating with Encore API

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    Client["Browser / HTTP Client"]:::client

    %% Frontend Layer
    subgraph "React Frontend"
        Frontend["React Frontend"]:::frontend
        App["App.tsx"]:::frontend
        ApiClient["api.ts"]:::frontend
        BillManager["BillManager.tsx"]:::frontend
    end

    %% API Layer
    subgraph "Encore API Service"
        API_Service["service.go"]:::api
        ServiceTypes["types.go"]:::api
        ServiceUtils["utils.go"]:::api
    end

    %% Orchestration Layer
    subgraph "Temporal Worker"
        WorkflowDefs["workflow.go"]:::workflow
        Activities["activities.go"]:::workflow
    end

    %% Database Layer
    subgraph "Postgres Database"
        Postgres["Postgres"]:::db
        Migrations["migrations/"]:::db
    end

    %% Infrastructure & Tests
    subgraph "Infra & Scripts"
        EncoreConfig["encore.app"]:::infra
        Scripts["scripts/"]:::infra
        ServiceTest["service_test.go"]:::infra
        WorkflowTest["workflow_test.go"]:::infra
    end

    %% Connections
    Client -->|"loads UI"| Frontend
    Frontend -->|"calls REST API"| API_Service
    API_Service -->|"startWorkflow / sendSignal"| WorkflowDefs
    API_Service -->|"direct SQL query"| Postgres
    WorkflowDefs -->|"invoke activity"| Activities
    Activities -->|"write / read SQL"| Postgres

    %% Click Events
    click Frontend "https://github.com/karansinghgit/feems/tree/main/frontend/"
    click App "https://github.com/karansinghgit/feems/blob/main/frontend/src/App.tsx"
    click ApiClient "https://github.com/karansinghgit/feems/blob/main/frontend/src/api.ts"
    click BillManager "https://github.com/karansinghgit/feems/blob/main/frontend/src/components/BillManager.tsx"
    click API_Service "https://github.com/karansinghgit/feems/blob/main/services/fees/service.go"
    click ServiceTypes "https://github.com/karansinghgit/feems/blob/main/services/fees/types.go"
    click ServiceUtils "https://github.com/karansinghgit/feems/blob/main/services/fees/utils.go"
    click WorkflowDefs "https://github.com/karansinghgit/feems/blob/main/services/fees/workflow.go"
    click Activities "https://github.com/karansinghgit/feems/blob/main/services/fees/activities.go"
    click Migrations "https://github.com/karansinghgit/feems/tree/main/services/fees/migrations/"
    click EncoreConfig "https://github.com/karansinghgit/feems/blob/main/encore.app"
    click Scripts "https://github.com/karansinghgit/feems/tree/main/scripts/"
    click ServiceTest "https://github.com/karansinghgit/feems/blob/main/services/fees/service_test.go"
    click WorkflowTest "https://github.com/karansinghgit/feems/blob/main/services/fees/workflow_test.go"

    %% Styles
    classDef client fill:#D0E6FF,stroke:#0366d6
    classDef frontend fill:#E8F4FF,stroke:#0366d6
    classDef api fill:#E6FFED,stroke:#28a745
    classDef workflow fill:#FFF5E6,stroke:#db8c00
    classDef db fill:#FFE6E6,stroke:#d73a49
    classDef infra fill:#F0F0F0,stroke:#6a737d
```
