# mysociety-team/development architecture

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

- Interactive diagram: https://gitdiagram.com/mysociety-team/development
- Repository: https://github.com/mysociety-team/development

## Overview

MySociety is a society-management application for residents, committee members, and administrators. Users authenticate, select or join a society, then use its resident and committee workflows: maintenance billing and payment, finance records, meetings, announcements, complaints, and contacts. The React client sends feature requests through a shared API client to Express routes and controllers; controllers delegate domain operations to services, with MongoDB-backed models. Notifications and subscriptions provide supporting capabilities. README documentation is limited to authentication routes, so feature-level wiring is based on the sampled controllers and the listed module structure.

Main entry points: [`server/src/routes/index.js`](https://github.com/mysociety-team/development/blob/development/server/src/routes/index.js) (API route registry), [`server/src/modules/maintenance/maintenance.service.js`](https://github.com/mysociety-team/development/blob/development/server/src/modules/maintenance/maintenance.service.js) (Domain services), [`client/src/app/router.jsx`](https://github.com/mysociety-team/development/blob/development/client/src/app/router.jsx) (Page router), [`client/src/lib/apiClient.js`](https://github.com/mysociety-team/development/blob/development/client/src/lib/apiClient.js) (HTTP API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["React application<br/>[App.jsx]"]
  node_router["Page router<br/>[router.jsx]"]
  node_api["HTTP API client<br/>[apiClient.js]"]
  node_authui["Sign in and register<br/>[LoginPage.jsx]"]
  node_societyui["Society selection<br/>[SocietiesPage.jsx]"]
  node_maintenanceui["Maintenance screens"]
  node_financeui["Finance screens<br/>[FinancePage.jsx]"]
  node_meetingsui["Meeting screens<br/>[MeetingsPage.jsx]"]
  node_communityui["Community screens"]
end

subgraph group_server["API runtime"]
  node_server["Express application<br/>[app.js]"]
  node_routes["API route registry<br/>[index.js]"]
  node_services["Domain services"]
  node_models[("Domain models<br/>[Society.js]")]
end

subgraph group_society["Society operations"]
  node_societyops["Society membership"]
  node_maintenance["Bills and payments"]
  node_finance["Society finance"]
end

subgraph group_community["Resident services"]
  node_meetings["Meetings and attendance"]
  node_announcements["Announcements"]
  node_complaints["Complaints"]
  node_contacts["Society contacts"]
  node_notifications["Notifications"]
end

subgraph group_platform["Identity and billing"]
  node_auth["Authentication<br/>[auth.controller.js]"]
  node_subscriptions["Subscriptions"]
end

node_user(("Resident or committee"))
node_mongo[("MongoDB")]
node_razorpay["Razorpay"]

node_user -->|"uses"| node_app
node_app -->|"renders"| node_router
node_router -->|"routes"| node_authui
node_router -->|"routes"| node_societyui
node_router -->|"routes"| node_maintenanceui
node_router -->|"routes"| node_financeui
node_router -->|"routes"| node_meetingsui
node_router -->|"routes"| node_communityui
node_authui -->|"requests"| node_api
node_societyui -->|"requests"| node_api
node_maintenanceui -->|"requests"| node_api
node_financeui -->|"requests"| node_api
node_meetingsui -->|"requests"| node_api
node_communityui -->|"requests"| node_api
node_api -->|"HTTP requests"| node_server
node_server -->|"dispatches"| node_routes
node_routes -->|"dispatches"| node_auth
node_routes -->|"dispatches"| node_societyops
node_routes -->|"dispatches"| node_maintenance
node_routes -->|"dispatches"| node_finance
node_routes -->|"dispatches"| node_meetings
node_routes -->|"dispatches"| node_announcements
node_routes -->|"dispatches"| node_complaints
node_routes -->|"dispatches"| node_contacts
node_routes -->|"dispatches"| node_notifications
node_routes -->|"dispatches"| node_subscriptions
node_auth -->|"reads and writes"| node_models
node_societyops -->|"calls"| node_services
node_maintenance -->|"calls"| node_services
node_finance -->|"calls"| node_services
node_meetings -->|"calls"| node_services
node_announcements -->|"calls"| node_services
node_complaints -->|"calls"| node_services
node_contacts -->|"calls"| node_services
node_notifications -->|"calls"| node_services
node_subscriptions -->|"calls"| node_services
node_services -->|"uses"| node_models
node_models -->|"persists"| node_mongo
node_services -.->|"payment integration"| node_razorpay

click node_app "https://github.com/mysociety-team/development/blob/development/client/src/App.jsx"
click node_router "https://github.com/mysociety-team/development/blob/development/client/src/app/router.jsx"
click node_api "https://github.com/mysociety-team/development/blob/development/client/src/lib/apiClient.js"
click node_authui "https://github.com/mysociety-team/development/blob/development/client/src/modules/auth/pages/LoginPage.jsx"
click node_societyui "https://github.com/mysociety-team/development/blob/development/client/src/modules/societies/pages/SocietiesPage.jsx"
click node_maintenanceui "https://github.com/mysociety-team/development/blob/development/client/src/modules/maintenance/pages/MaintenancePage.jsx"
click node_financeui "https://github.com/mysociety-team/development/blob/development/client/src/modules/finance/pages/FinancePage.jsx"
click node_meetingsui "https://github.com/mysociety-team/development/blob/development/client/src/modules/meetings/pages/MeetingsPage.jsx"
click node_communityui "https://github.com/mysociety-team/development/blob/development/client/src/modules/announcements/pages/AnnouncementsPage.jsx"
click node_server "https://github.com/mysociety-team/development/blob/development/server/src/app.js"
click node_routes "https://github.com/mysociety-team/development/blob/development/server/src/routes/index.js"
click node_auth "https://github.com/mysociety-team/development/blob/development/server/src/modules/auth/auth.controller.js"
click node_societyops "https://github.com/mysociety-team/development/blob/development/server/src/modules/societies/society.controller.js"
click node_maintenance "https://github.com/mysociety-team/development/blob/development/server/src/modules/maintenance/maintenance.controller.js"
click node_finance "https://github.com/mysociety-team/development/blob/development/server/src/modules/finance/finance.controller.js"
click node_meetings "https://github.com/mysociety-team/development/blob/development/server/src/modules/meetings/meeting.controller.js"
click node_announcements "https://github.com/mysociety-team/development/blob/development/server/src/modules/announcements/announcement.controller.js"
click node_complaints "https://github.com/mysociety-team/development/blob/development/server/src/modules/complaints/complaint.controller.js"
click node_contacts "https://github.com/mysociety-team/development/blob/development/server/src/modules/contacts/contact.controller.js"
click node_notifications "https://github.com/mysociety-team/development/blob/development/server/src/modules/notifications/notification.controller.js"
click node_subscriptions "https://github.com/mysociety-team/development/blob/development/server/src/modules/subscriptions/subscription.controller.js"
click node_services "https://github.com/mysociety-team/development/blob/development/server/src/modules/maintenance/maintenance.service.js"
click node_models "https://github.com/mysociety-team/development/blob/development/server/src/models/Society.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_app,node_router,node_api,node_authui,node_societyui,node_maintenanceui,node_financeui,node_meetingsui,node_communityui toneBlue
class node_server,node_routes,node_services,node_models,node_mongo toneAmber
class node_societyops,node_maintenance,node_finance toneMint
class node_meetings,node_announcements,node_complaints,node_contacts,node_notifications toneRose
class node_auth,node_subscriptions,node_user,node_razorpay toneIndigo
```

## Components

### Web client

- [React application](https://github.com/mysociety-team/development/blob/development/client/src/App.jsx): `client/src/App.jsx`
- [Page router](https://github.com/mysociety-team/development/blob/development/client/src/app/router.jsx): `client/src/app/router.jsx`
- [HTTP API client](https://github.com/mysociety-team/development/blob/development/client/src/lib/apiClient.js): `client/src/lib/apiClient.js`
- [Sign in and register](https://github.com/mysociety-team/development/blob/development/client/src/modules/auth/pages/LoginPage.jsx): `client/src/modules/auth/pages/LoginPage.jsx`
- [Society selection](https://github.com/mysociety-team/development/blob/development/client/src/modules/societies/pages/SocietiesPage.jsx): `client/src/modules/societies/pages/SocietiesPage.jsx`
- [Maintenance screens](https://github.com/mysociety-team/development/blob/development/client/src/modules/maintenance/pages/MaintenancePage.jsx): `client/src/modules/maintenance/pages/MaintenancePage.jsx`
- [Finance screens](https://github.com/mysociety-team/development/blob/development/client/src/modules/finance/pages/FinancePage.jsx): `client/src/modules/finance/pages/FinancePage.jsx`
- [Meeting screens](https://github.com/mysociety-team/development/blob/development/client/src/modules/meetings/pages/MeetingsPage.jsx): `client/src/modules/meetings/pages/MeetingsPage.jsx`
- [Community screens](https://github.com/mysociety-team/development/blob/development/client/src/modules/announcements/pages/AnnouncementsPage.jsx): `client/src/modules/announcements/pages/AnnouncementsPage.jsx`

### API runtime

- [Express application](https://github.com/mysociety-team/development/blob/development/server/src/app.js): `server/src/app.js`
- [API route registry](https://github.com/mysociety-team/development/blob/development/server/src/routes/index.js): `server/src/routes/index.js`
- [Domain services](https://github.com/mysociety-team/development/blob/development/server/src/modules/maintenance/maintenance.service.js): `server/src/modules/maintenance/maintenance.service.js`
- [Domain models](https://github.com/mysociety-team/development/blob/development/server/src/models/Society.js): `server/src/models/Society.js`

### Society operations

- [Society membership](https://github.com/mysociety-team/development/blob/development/server/src/modules/societies/society.controller.js): `server/src/modules/societies/society.controller.js`
- [Bills and payments](https://github.com/mysociety-team/development/blob/development/server/src/modules/maintenance/maintenance.controller.js): `server/src/modules/maintenance/maintenance.controller.js`
- [Society finance](https://github.com/mysociety-team/development/blob/development/server/src/modules/finance/finance.controller.js): `server/src/modules/finance/finance.controller.js`

### Resident services

- [Meetings and attendance](https://github.com/mysociety-team/development/blob/development/server/src/modules/meetings/meeting.controller.js): `server/src/modules/meetings/meeting.controller.js`
- [Announcements](https://github.com/mysociety-team/development/blob/development/server/src/modules/announcements/announcement.controller.js): `server/src/modules/announcements/announcement.controller.js`
- [Complaints](https://github.com/mysociety-team/development/blob/development/server/src/modules/complaints/complaint.controller.js): `server/src/modules/complaints/complaint.controller.js`
- [Society contacts](https://github.com/mysociety-team/development/blob/development/server/src/modules/contacts/contact.controller.js): `server/src/modules/contacts/contact.controller.js`
- [Notifications](https://github.com/mysociety-team/development/blob/development/server/src/modules/notifications/notification.controller.js): `server/src/modules/notifications/notification.controller.js`

### Identity and billing

- [Authentication](https://github.com/mysociety-team/development/blob/development/server/src/modules/auth/auth.controller.js): `server/src/modules/auth/auth.controller.js`
- [Subscriptions](https://github.com/mysociety-team/development/blob/development/server/src/modules/subscriptions/subscription.controller.js): `server/src/modules/subscriptions/subscription.controller.js`

### Other components

- **Resident or committee**
- **MongoDB**
- **Razorpay**

## Connections

- Resident or committee → React application: uses
- React application → Page router: renders
- Page router → Sign in and register: routes
- Page router → Society selection: routes
- Page router → Maintenance screens: routes
- Page router → Finance screens: routes
- Page router → Meeting screens: routes
- Page router → Community screens: routes
- Sign in and register → HTTP API client: requests
- Society selection → HTTP API client: requests
- Maintenance screens → HTTP API client: requests
- Finance screens → HTTP API client: requests
- Meeting screens → HTTP API client: requests
- Community screens → HTTP API client: requests
- HTTP API client → Express application: HTTP requests
- Express application → API route registry: dispatches
- API route registry → Authentication: dispatches
- API route registry → Society membership: dispatches
- API route registry → Bills and payments: dispatches
- API route registry → Society finance: dispatches
- API route registry → Meetings and attendance: dispatches
- API route registry → Announcements: dispatches
- API route registry → Complaints: dispatches
- API route registry → Society contacts: dispatches
- API route registry → Notifications: dispatches
- API route registry → Subscriptions: dispatches
- Authentication → Domain models: reads and writes
- Society membership → Domain services: calls
- Bills and payments → Domain services: calls
- Society finance → Domain services: calls
- Meetings and attendance → Domain services: calls
- Announcements → Domain services: calls
- Complaints → Domain services: calls
- Society contacts → Domain services: calls
- Notifications → Domain services: calls
- Subscriptions → Domain services: calls
- Domain services → Domain models: uses
- Domain models → MongoDB: persists
- Domain services → Razorpay: payment integration