# fuzz3rr/overseer architecture

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

- Interactive diagram: https://gitdiagram.com/fuzz3rr/overseer
- Repository: https://github.com/fuzz3rr/overseer

## Overview

1. **Overall shape**
   - This is a **React single-page frontend** with a conventional **Redux** state layer and a **service/API boundary**.
   - The app is organized around user account management, projects, and project integrations rather than a generic UI shell.

2. **Entry points and app shell**
   - `src/index.js` bootstraps the app.
   - `src/App.js`, `src/Routes.js`, and `src/Store.js` define the top-level composition: routing, global store, and shared app structure.
   - `src/components/Layout.js`, `Header.js`, and `Footer.js` provide the persistent shell around routed pages.

3. **Routing and access control**
   - `src/pages/*` contains route-level screens such as login, registration, account, project detail, integration detail, and password reset flows.
   - `src/components/OnlyLoggedInRoute.js` acts as an auth gate for protected areas.
   - `src/components/NotFoundComponent.js` and `src/pages/Page404.js` handle missing routes or unknown views.

4. **Domain boundaries**
   - The main business domain is split into:
     - **Users/authentication**
     - **Projects**
     - **Telegram integrations**
     - **Webhook integrations**
   - The repository’s component and action structure mirrors those domains, which makes the architecture easy to diagram as separate vertical slices.

5. **Global state management**
   - `src/redux/` contains the application state layer, divided into:
     - `actions/`
     - `reducers/`
     - `constants/`
   - State appears to cover auth, alerts, errors, modal UI, projects, Telegram integrations, and webhook integrations.
   - `src/redux/index.js` and `src/redux/reducers/index.js` assemble the Redux store shape.

6. **Backend/API boundary**
   - `src/services/UserApi.js`, `ProjectApi.js`, and `IntegrationApi.js` are the primary client-side boundaries to the backend.
   - Redux actions call these services, and reducers consume the resulting success/failure actions.
   - This means the UI does not appear to talk directly to the backend from components; the service/action layer mediates all remote data access.

7. **Authentication and session flow**
   - `src/components/forms/LoginForm.js`, `RegisterForm.js`, `RequestNewPasswordForm.js`, `NewPasswordForm.js`, `ChangePasswordForm.js`, and `DeleteAccountForm.js` cover the auth/account lifecycle.
   - `src/redux/actions/auth.actions.js` and `src/redux/reducers/auth.reducer.js` likely manage login state, tokens, and session transitions.
   - `src/util/JwtDecoder.js` and `src/util/DispatchWithTokenRefresh.js` suggest token-based auth with refresh handling when requests expire.

8. **Project management flow**
   - Projects are a first-class entity with list/detail/edit/create screens: `ProjectList.js`, `pages/Home.js`, `pages/Project.js`, `pages/NewProject.js`, `pages/EditProject.js`.
   - `src/components/ProjectCard/*` decomposes the project detail view into rows for title, members, invitations, errors, API keys, Telegram integrations, and webhook integrations.
   - This indicates a project dashboard that aggregates multiple related resources under one project boundary.

9. **Integration management flow**
   - Telegram and webhook integrations each have their own create/edit/detail pages and card components.
   - Telegram-specific UI lives in `TelegramIntegrationCard/*`, `forms/TelegramIntegrationForm.js`, and pages like `NewTelegramIntegration.js`, `EditTelegramIntegration.js`, `TelegramIntegration.js`.
   - Webhook-specific UI lives in `WebhookIntegrationCard/*`, `forms/WebhookIntegrationForm.js`, and corresponding pages.
   - These are likely child resources of a project and are managed through the shared integration service layer.

10. **Cross-cutting UI concerns**
   - `src/components/Alert.js`, `src/components/ErrorCard/*`, and `src/pages/Error.js` handle user-visible failure states.
   - `src/redux/actions/alert.actions.js`, `error.actions.js`, and related reducers support global notification/error presentation.
   - `src/components/Seo.js` suggests page-level metadata management, and `src/components/Modal`-style state is represented in Redux via `modal.*`.

11. **Utilities and formatting**
   - `src/util/ProjectAuthorizationService.js` appears to encapsulate permission checks for project-scoped actions.
   - `TimestampParser.js` and `TextFormatter.js` provide presentation helpers for dates and text.
   - `src/hooks/useDebounce.js` is a small reusable UI hook, likely used to reduce noisy input-driven requests or updates.

12. **Runtime and packaging signals**
   - The presence of `public/manifest.json`, `robots.txt`, and `index.html` indicates a standard browser-deployed frontend bundle.
   - `package.json` and `package-lock.json` suggest a Node/npm-based build and dependency pipeline.
   - Overall, this is a client-side application that depends on external backend APIs for authentication and domain data, with Redux coordinating UI state and async request lifecycles.

Main entry points: [`src/Routes.js`](https://github.com/fuzz3rr/overseer/blob/main/src/Routes.js) (Routes), [`src/App.js`](https://github.com/fuzz3rr/overseer/blob/main/src/App.js) (App), [`src/pages/TelegramIntegration.js`](https://github.com/fuzz3rr/overseer/blob/main/src/pages/TelegramIntegration.js) (Integrations), [`src/redux/reducers/index.js`](https://github.com/fuzz3rr/overseer/blob/main/src/redux/reducers/index.js) (Reducers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App shell"]
  node_src_index(("index<br/>bootstrap<br/>[index.js]"))
  node_src_app["App<br/>composition<br/>[App.js]"]
  node_src_routes["Routes<br/>routing<br/>[Routes.js]"]
end

subgraph group_state["Redux state"]
  node_src_store[("Store<br/>[Store.js]")]
  node_redux_root[("Redux root<br/>state assembly<br/>[index.js]")]
  node_redux_reducers[("Reducers<br/>state slices<br/>[index.js]")]
  node_auth_actions["Auth actions<br/>redux actions<br/>[auth.actions.js]"]
  node_project_actions["Project actions<br/>redux actions<br/>[project.actions.js]"]
  node_integration_actions["Integration actions<br/>redux actions"]
end

subgraph group_api["API layer"]
  node_user_api["User API<br/>[UserApi.js]"]
  node_project_api["Project API<br/>[ProjectApi.js]"]
  node_integration_api["Integration API<br/>[IntegrationApi.js]"]
end

subgraph group_domain["Domain UI"]
  node_auth_pages["Auth pages<br/>screens<br/>[Login.js]"]
  node_project_pages["Projects<br/>screens<br/>[Home.js]"]
  node_integration_pages["Integrations<br/>screens"]
  node_project_card["Project card<br/>project ui<br/>[ProjectCard.js]"]
  node_telegram_card["Telegram card<br/>integration ui"]
  node_webhook_card["Webhook card<br/>integration ui"]
end

subgraph group_shared["Shared UI"]
  node_layout["Layout<br/>shell<br/>[Layout.js]"]
  node_guard["Auth guard<br/>route guard"]
  node_alerts["Alerts<br/>feedback ui<br/>[Alert.js]"]
  node_forms["Forms<br/>input ui<br/>[index.js]"]
end

subgraph group_util["Utilities"]
  node_jwt["JWT utils<br/>auth util<br/>[JwtDecoder.js]"]
  node_authz["Project auth<br/>permission util"]
end

node_src_index -->|"bootstraps"| node_src_app
node_src_app -->|"uses"| node_src_routes
node_src_app -->|"wraps"| node_layout
node_src_app -->|"connects"| node_src_store
node_src_store -->|"builds"| node_redux_root
node_redux_root -->|"combines"| node_redux_reducers
node_src_routes -->|"protects"| node_guard
node_src_routes -->|"routes to"| node_auth_pages
node_src_routes -->|"routes to"| node_project_pages
node_src_routes -->|"routes to"| node_integration_pages
node_project_pages -->|"renders"| node_project_card
node_integration_pages -->|"renders"| node_telegram_card
node_integration_pages -->|"renders"| node_webhook_card
node_auth_pages -->|"uses"| node_forms
node_project_pages -->|"uses"| node_forms
node_integration_pages -->|"uses"| node_forms
node_auth_actions -->|"calls"| node_user_api
node_project_actions -->|"calls"| node_project_api
node_integration_actions -->|"calls"| node_integration_api
node_auth_actions -->|"updates"| node_redux_reducers
node_project_actions -->|"updates"| node_redux_reducers
node_integration_actions -->|"updates"| node_redux_reducers
node_layout -->|"shows"| node_alerts
node_guard -->|"relies on"| node_jwt
node_project_card -->|"checks"| node_authz

click node_src_index "https://github.com/fuzz3rr/overseer/blob/main/src/index.js"
click node_src_app "https://github.com/fuzz3rr/overseer/blob/main/src/App.js"
click node_src_routes "https://github.com/fuzz3rr/overseer/blob/main/src/Routes.js"
click node_src_store "https://github.com/fuzz3rr/overseer/blob/main/src/Store.js"
click node_redux_root "https://github.com/fuzz3rr/overseer/blob/main/src/redux/index.js"
click node_redux_reducers "https://github.com/fuzz3rr/overseer/blob/main/src/redux/reducers/index.js"
click node_auth_actions "https://github.com/fuzz3rr/overseer/blob/main/src/redux/actions/auth.actions.js"
click node_project_actions "https://github.com/fuzz3rr/overseer/blob/main/src/redux/actions/project.actions.js"
click node_integration_actions "https://github.com/fuzz3rr/overseer/blob/main/src/redux/actions/telegram-integration.actions.js"
click node_user_api "https://github.com/fuzz3rr/overseer/blob/main/src/services/UserApi.js"
click node_project_api "https://github.com/fuzz3rr/overseer/blob/main/src/services/ProjectApi.js"
click node_integration_api "https://github.com/fuzz3rr/overseer/blob/main/src/services/IntegrationApi.js"
click node_auth_pages "https://github.com/fuzz3rr/overseer/blob/main/src/pages/Login.js"
click node_project_pages "https://github.com/fuzz3rr/overseer/blob/main/src/pages/Home.js"
click node_integration_pages "https://github.com/fuzz3rr/overseer/blob/main/src/pages/TelegramIntegration.js"
click node_project_card "https://github.com/fuzz3rr/overseer/blob/main/src/components/ProjectCard/ProjectCard.js"
click node_telegram_card "https://github.com/fuzz3rr/overseer/blob/main/src/components/TelegramIntegrationCard/TelegramIntegrationCard.js"
click node_webhook_card "https://github.com/fuzz3rr/overseer/blob/main/src/components/WebhookIntegrationCard/WebhookIntegrationCard.js"
click node_layout "https://github.com/fuzz3rr/overseer/blob/main/src/components/Layout.js"
click node_guard "https://github.com/fuzz3rr/overseer/blob/main/src/components/OnlyLoggedInRoute.js"
click node_alerts "https://github.com/fuzz3rr/overseer/blob/main/src/components/Alert.js"
click node_forms "https://github.com/fuzz3rr/overseer/blob/main/src/components/forms/index.js"
click node_jwt "https://github.com/fuzz3rr/overseer/blob/main/src/util/JwtDecoder.js"
click node_authz "https://github.com/fuzz3rr/overseer/blob/main/src/util/ProjectAuthorizationService.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_index,node_src_app,node_src_routes toneBlue
class node_src_store,node_redux_root,node_redux_reducers,node_auth_actions,node_project_actions,node_integration_actions toneAmber
class node_user_api,node_project_api,node_integration_api toneMint
class node_auth_pages,node_project_pages,node_integration_pages,node_project_card,node_telegram_card,node_webhook_card toneRose
class node_layout,node_guard,node_alerts,node_forms toneIndigo
class node_jwt,node_authz toneTeal
```

## Components

### App shell

Bootstrap, routing, and persistent layout

- [index](https://github.com/fuzz3rr/overseer/blob/main/src/index.js): bootstrap · Browser entry point that mounts the app · `src/index.js`
- [App](https://github.com/fuzz3rr/overseer/blob/main/src/App.js): composition · Top-level application composition · `src/App.js`
- [Routes](https://github.com/fuzz3rr/overseer/blob/main/src/Routes.js): routing · Route table and screen selection · `src/Routes.js`

### Redux state

Store, actions, reducers, and domain state

- [Store](https://github.com/fuzz3rr/overseer/blob/main/src/Store.js): redux store · Global state wiring · `src/Store.js`
- [Redux root](https://github.com/fuzz3rr/overseer/blob/main/src/redux/index.js): state assembly · Combines reducers and exports state shape · `src/redux/index.js`
- [Reducers](https://github.com/fuzz3rr/overseer/blob/main/src/redux/reducers/index.js): state slices · Auth, projects, integrations, alerts, errors, modal · `src/redux/reducers/index.js`
- [Auth actions](https://github.com/fuzz3rr/overseer/blob/main/src/redux/actions/auth.actions.js): redux actions · Session and account workflows · `src/redux/actions/auth.actions.js`
- [Project actions](https://github.com/fuzz3rr/overseer/blob/main/src/redux/actions/project.actions.js): redux actions · Project lifecycle and project-scoped fetches · `src/redux/actions/project.actions.js`
- [Integration actions](https://github.com/fuzz3rr/overseer/blob/main/src/redux/actions/telegram-integration.actions.js): redux actions · Telegram and webhook integration workflows · `src/redux/actions/telegram-integration.actions.js`

### API layer

Client-side services for backend access

- [User API](https://github.com/fuzz3rr/overseer/blob/main/src/services/UserApi.js): service · Backend boundary for auth and account calls · `src/services/UserApi.js`
- [Project API](https://github.com/fuzz3rr/overseer/blob/main/src/services/ProjectApi.js): service · Backend boundary for project calls · `src/services/ProjectApi.js`
- [Integration API](https://github.com/fuzz3rr/overseer/blob/main/src/services/IntegrationApi.js): service · Backend boundary for integration calls · `src/services/IntegrationApi.js`

### Domain UI

Route screens and major feature components

- [Auth pages](https://github.com/fuzz3rr/overseer/blob/main/src/pages/Login.js): screens · Login, register, password reset, account, logout · `src/pages/Login.js`
- [Projects](https://github.com/fuzz3rr/overseer/blob/main/src/pages/Home.js): screens · Project list, detail, create, edit, invitations · `src/pages/Home.js`
- [Integrations](https://github.com/fuzz3rr/overseer/blob/main/src/pages/TelegramIntegration.js): screens · Telegram and webhook detail, create, edit · `src/pages/TelegramIntegration.js`
- [Project card](https://github.com/fuzz3rr/overseer/blob/main/src/components/ProjectCard/ProjectCard.js): project ui · Project dashboard rows for members, keys, and integrations · `src/components/ProjectCard/ProjectCard.js`
- [Telegram card](https://github.com/fuzz3rr/overseer/blob/main/src/components/TelegramIntegrationCard/TelegramIntegrationCard.js): integration ui · Telegram integration detail components · `src/components/TelegramIntegrationCard/TelegramIntegrationCard.js`
- [Webhook card](https://github.com/fuzz3rr/overseer/blob/main/src/components/WebhookIntegrationCard/WebhookIntegrationCard.js): integration ui · Webhook integration detail components · `src/components/WebhookIntegrationCard/WebhookIntegrationCard.js`

### Shared UI

Reusable components and cross-cutting UI

- [Layout](https://github.com/fuzz3rr/overseer/blob/main/src/components/Layout.js): shell · Persistent page chrome · `src/components/Layout.js`
- [Auth guard](https://github.com/fuzz3rr/overseer/blob/main/src/components/OnlyLoggedInRoute.js): route guard · Protects logged-in routes · `src/components/OnlyLoggedInRoute.js`
- [Alerts](https://github.com/fuzz3rr/overseer/blob/main/src/components/Alert.js): feedback ui · Global alerts and error presentation · `src/components/Alert.js`
- [Forms](https://github.com/fuzz3rr/overseer/blob/main/src/components/forms/index.js): input ui · Login, registration, project, and integration forms · `src/components/forms/index.js`

### Utilities

Auth, formatting, and small helpers

- [JWT utils](https://github.com/fuzz3rr/overseer/blob/main/src/util/JwtDecoder.js): auth util · Token decoding and refresh dispatch wrapper · `src/util/JwtDecoder.js`
- [Project auth](https://github.com/fuzz3rr/overseer/blob/main/src/util/ProjectAuthorizationService.js): permission util · Project-scoped authorization checks · `src/util/ProjectAuthorizationService.js`

## Connections

- index → App: bootstraps · Entry point mounts the root app
- App → Routes: uses · App delegates screen selection to routes
- App → Layout: wraps · Shared shell surrounds routed pages
- App → Store: connects · App is provided global Redux state
- Store → Redux root: builds · Store is created from combined reducers
- Redux root → Reducers: combines · Root reducer assembles domain slices
- Routes → Auth guard: protects · Private routes are gated by login state
- Routes → Auth pages: routes to · Public auth and account screens
- Routes → Projects: routes to · Project screens
- Routes → Integrations: routes to · Integration screens
- Projects → Project card: renders · Project detail page composes project dashboard sections
- Integrations → Telegram card: renders · Telegram integration pages use detail card
- Integrations → Webhook card: renders · Webhook integration pages use detail card
- Auth pages → Forms: uses · Auth flows are driven by reusable forms
- Projects → Forms: uses · Project create/edit flows use forms
- Integrations → Forms: uses · Integration create/edit flows use forms
- Auth actions → User API: calls · Auth actions mediate all user/account requests
- Project actions → Project API: calls · Project actions mediate project requests
- Integration actions → Integration API: calls · Integration actions mediate Telegram/webhook requests
- Auth actions → Reducers: updates · Auth action results flow into reducers
- Project actions → Reducers: updates · Project action results flow into reducers
- Integration actions → Reducers: updates · Integration action results flow into reducers
- Layout → Alerts: shows · Shell surfaces global notifications and failures
- Auth guard → JWT utils: relies on · Protected routing depends on token/session helpers
- Project card → Project auth: checks · Project UI uses permission logic for scoped actions
