# gaikawadaprasad/gatesphere architecture

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

- Interactive diagram: https://gitdiagram.com/gaikawadaprasad/gatesphere
- Repository: https://github.com/gaikawadaprasad/gatesphere

## Overview

GateSphere is a multi-tenant residential community operations platform, with role-specific web experiences backed by a FastAPI service. A typical workflow starts when a resident, guard, or administrator uses a role-based page to request an operation; the API routes it to a domain service, which enforces community scope and updates application data. The documented product also covers billing, communications, amenities, staff, deliveries, dashboards, and audit. Domain modules and several integrations are clear from the tree and README; detailed wiring for unsampled modules is therefore shown only at the application boundary.

Main entry points: [`backend/app/api/router.py`](https://github.com/gaikawadaprasad/gatesphere/blob/main/backend/app/api/router.py) (API router), [`backend/app/db/session.py`](https://github.com/gaikawadaprasad/gatesphere/blob/main/backend/app/db/session.py) (Application database), [`backend/app/main.py`](https://github.com/gaikawadaprasad/gatesphere/blob/main/backend/app/main.py) (FastAPI application), [`frontend/app`](https://github.com/gaikawadaprasad/gatesphere/tree/main/frontend/app) (Role-based web app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_web_app["Role-based web app"]
  node_web_api["API client<br/>[api.ts]"]
end

subgraph group_api["API and access"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_api_router["API router<br/>[router.py]"]
  node_auth["Authentication"]
  node_rbac["Roles and permissions"]
end

subgraph group_operations["Community operations"]
  node_onboarding["Tenant onboarding"]
  node_residents["Residents and units"]
  node_visitors["Visitor lifecycle"]
  node_gate["Gate operations"]
  node_staff["Domestic staff"]
  node_deliveries["Deliveries and vehicles"]
  node_facilities["Facilities and complaints"]
  node_incidents["Incidents and emergencies"]
end

subgraph group_oversight["Finance and oversight"]
  node_billing["Maintenance billing"]
  node_communications["Announcements and polls"]
  node_dashboards["Dashboards and reporting"]
  node_audit["Audit trail"]
end

subgraph group_platform["Shared platform"]
  node_db[("Application database<br/>[session.py]")]
  node_uploads["Upload handling"]
  node_object_store[("S3-compatible storage<br/>[storage.py]")]
  node_notifications["Notifications"]
  node_jobs["Background jobs<br/>[celery_app.py]"]
  node_redis[("Redis<br/>[redis.py]")]
end

node_resident_actor(("Community users"))

node_resident_actor -->|"uses"| node_web_app
node_web_app -->|"requests data"| node_web_api
node_web_api -->|"sends API requests"| node_api_app
node_api_app -->|"dispatches routes"| node_api_router
node_api_router -->|"routes auth"| node_auth
node_api_router -->|"routes access"| node_rbac
node_api_router -->|"routes onboarding"| node_onboarding
node_api_router -->|"routes resident operations"| node_residents
node_api_router -->|"routes visitor operations"| node_visitors
node_api_router -->|"routes gate operations"| node_gate
node_api_router -->|"routes staff operations"| node_staff
node_api_router -->|"routes deliveries"| node_deliveries
node_api_router -->|"routes facility operations"| node_facilities
node_api_router -->|"routes incidents"| node_incidents
node_api_router -->|"routes billing"| node_billing
node_api_router -->|"routes communication"| node_communications
node_api_router -->|"routes dashboards"| node_dashboards
node_api_router -->|"routes audit queries"| node_audit
node_uploads -->|"stores objects"| node_object_store
node_communications -->|"queues broadcast work"| node_jobs
node_jobs -->|"dispatches notification work"| node_notifications
node_audit -->|"reads audit data"| node_db
node_dashboards -->|"reads operational data"| node_db
node_visitors -->|"persists visitor records"| node_db
node_billing -->|"persists invoices and payments"| node_db
node_api_app -->|"checks readiness"| node_redis

click node_web_app "https://github.com/gaikawadaprasad/gatesphere/tree/main/frontend/app"
click node_web_api "https://github.com/gaikawadaprasad/gatesphere/blob/main/frontend/lib/api.ts"
click node_api_app "https://github.com/gaikawadaprasad/gatesphere/blob/main/backend/app/main.py"
click node_api_router "https://github.com/gaikawadaprasad/gatesphere/blob/main/backend/app/api/router.py"
click node_auth "https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/auth"
click node_rbac "https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/rbac"
click node_onboarding "https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/onboarding"
click node_residents "https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/residents"
click node_visitors "https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/visitors"
click node_gate "https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/gate"
click node_staff "https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/domestic_staff"
click node_deliveries "https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/deliveries"
click node_facilities "https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/amenities"
click node_incidents "https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/incidents"
click node_billing "https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/billing"
click node_communications "https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/communication"
click node_dashboards "https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/dashboards"
click node_audit "https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/audit"
click node_db "https://github.com/gaikawadaprasad/gatesphere/blob/main/backend/app/db/session.py"
click node_uploads "https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/uploads"
click node_object_store "https://github.com/gaikawadaprasad/gatesphere/blob/main/backend/app/services/storage.py"
click node_notifications "https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/notifications"
click node_jobs "https://github.com/gaikawadaprasad/gatesphere/blob/main/backend/app/core/celery_app.py"
click node_redis "https://github.com/gaikawadaprasad/gatesphere/blob/main/backend/app/core/redis.py"

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_web_app,node_web_api,node_resident_actor toneBlue
class node_api_app,node_api_router,node_auth,node_rbac toneAmber
class node_onboarding,node_residents,node_visitors,node_gate,node_staff,node_deliveries,node_facilities,node_incidents toneMint
class node_billing,node_communications,node_dashboards,node_audit toneRose
class node_db,node_uploads,node_object_store,node_notifications,node_jobs,node_redis toneIndigo
```

## Components

### Web experience

- [Role-based web app](https://github.com/gaikawadaprasad/gatesphere/tree/main/frontend/app): `frontend/app`
- [API client](https://github.com/gaikawadaprasad/gatesphere/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`

### API and access

- [FastAPI application](https://github.com/gaikawadaprasad/gatesphere/blob/main/backend/app/main.py): `backend/app/main.py`
- [API router](https://github.com/gaikawadaprasad/gatesphere/blob/main/backend/app/api/router.py): `backend/app/api/router.py`
- [Authentication](https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/auth): `backend/app/modules/auth`
- [Roles and permissions](https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/rbac): `backend/app/modules/rbac`

### Community operations

- [Tenant onboarding](https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/onboarding): `backend/app/modules/onboarding`
- [Residents and units](https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/residents): `backend/app/modules/residents`
- [Visitor lifecycle](https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/visitors): `backend/app/modules/visitors`
- [Gate operations](https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/gate): `backend/app/modules/gate`
- [Domestic staff](https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/domestic_staff): `backend/app/modules/domestic_staff`
- [Deliveries and vehicles](https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/deliveries): `backend/app/modules/deliveries`
- [Facilities and complaints](https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/amenities): `backend/app/modules/amenities`
- [Incidents and emergencies](https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/incidents): `backend/app/modules/incidents`

### Finance and oversight

- [Maintenance billing](https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/billing): `backend/app/modules/billing`
- [Announcements and polls](https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/communication): `backend/app/modules/communication`
- [Dashboards and reporting](https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/dashboards): `backend/app/modules/dashboards`
- [Audit trail](https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/audit): `backend/app/modules/audit`

### Shared platform

- [Application database](https://github.com/gaikawadaprasad/gatesphere/blob/main/backend/app/db/session.py): `backend/app/db/session.py`
- [Upload handling](https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/uploads): `backend/app/modules/uploads`
- [S3-compatible storage](https://github.com/gaikawadaprasad/gatesphere/blob/main/backend/app/services/storage.py): `backend/app/services/storage.py`
- [Notifications](https://github.com/gaikawadaprasad/gatesphere/tree/main/backend/app/modules/notifications): `backend/app/modules/notifications`
- [Background jobs](https://github.com/gaikawadaprasad/gatesphere/blob/main/backend/app/core/celery_app.py): `backend/app/core/celery_app.py`
- [Redis](https://github.com/gaikawadaprasad/gatesphere/blob/main/backend/app/core/redis.py): `backend/app/core/redis.py`

### Other components

- **Community users**

## Connections

- Community users → Role-based web app: uses
- Role-based web app → API client: requests data
- API client → FastAPI application: sends API requests
- FastAPI application → API router: dispatches routes
- API router → Authentication: routes auth
- API router → Roles and permissions: routes access
- API router → Tenant onboarding: routes onboarding
- API router → Residents and units: routes resident operations
- API router → Visitor lifecycle: routes visitor operations
- API router → Gate operations: routes gate operations
- API router → Domestic staff: routes staff operations
- API router → Deliveries and vehicles: routes deliveries
- API router → Facilities and complaints: routes facility operations
- API router → Incidents and emergencies: routes incidents
- API router → Maintenance billing: routes billing
- API router → Announcements and polls: routes communication
- API router → Dashboards and reporting: routes dashboards
- API router → Audit trail: routes audit queries
- Upload handling → S3-compatible storage: stores objects
- Announcements and polls → Background jobs: queues broadcast work
- Background jobs → Notifications: dispatches notification work
- Audit trail → Application database: reads audit data
- Dashboards and reporting → Application database: reads operational data
- Visitor lifecycle → Application database: persists visitor records
- Maintenance billing → Application database: persists invoices and payments
- FastAPI application → Redis: checks readiness