# cnpm-svbk-team13/bluemoon-apartment-management-system architecture

> Architecture diagram of the GitHub repository cnpm-svbk-team13/bluemoon-apartment-management-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cnpm-svbk-team13/bluemoon-apartment-management-system
- Repository: https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system

## Overview

BlueMoon BFMS is a Spring Boot web scaffold for apartment and household administration. The evidenced workflow is an administrator managing apartment records or household-head details: Spring MVC controllers delegate to services, which read and write through Spring Data repositories and JPA-backed domain models. The README also describes fees, invoices, reports, and a future resident portal, but this tree does not show implementations for those capabilities. Several controller and service relationships are supported by the source index; the broader web-to-database layering is documented in the README.

Main entry points: [`src/main/java/com/bluemoon/bfms/service/HouseholdHeadService.java`](https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/service/HouseholdHeadService.java) (Household-head changes), [`src/main/java/com/bluemoon/bfms/service/HouseholdDetailsService.java`](https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/service/HouseholdDetailsService.java) (Household details), [`src/main/java/com/bluemoon/bfms/service/ApartmentService.java`](https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/service/ApartmentService.java) (Apartment management), [`src/main/java/com/bluemoon/bfms/repository/ApartmentRepository.java`](https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/repository/ApartmentRepository.java) (Apartment repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_mvc["Spring MVC"]
  node_apartment_controller["Apartment routes"]
  node_household_controller["Household routes"]
end

subgraph group_business["Business services"]
  node_apartment_service["Apartment management"]
  node_access_service["Apartment access"]
  node_household_service["Household-head changes"]
  node_details_service["Household details"]
end

subgraph group_persistence["Persistence"]
  node_apartment_repo["Apartment repository"]
  node_household_repo["Household repository"]
  node_resident_repo["Resident repository"]
  node_person_repo["Person repository"]
  node_history_repo["Head-history repository"]
  node_actor_repo["Apartment actor repository"]
  node_user_repo["User repository"]
  node_audit_repo["Audit repository"]
end

subgraph group_domain["Domain data"]
  node_models["Apartment and household entities"]
  node_people["People and resident entities"]
  node_history_model["Head-change history"]
  node_audit_model["Audit log<br/>[AuditLog.java]"]
end

node_administrator(("Administrator"))
node_database[("PostgreSQL")]

node_administrator -->|"uses web app"| node_mvc
node_mvc -.->|"routes requests"| node_apartment_controller
node_mvc -.->|"routes requests"| node_household_controller
node_apartment_controller -->|"delegates to"| node_apartment_service
node_apartment_controller -->|"checks access"| node_access_service
node_household_controller -->|"delegates to"| node_household_service
node_household_controller -->|"loads details"| node_details_service
node_apartment_service -->|"reads and writes"| node_apartment_repo
node_apartment_service -->|"resolves actor"| node_user_repo
node_apartment_service -->|"records audit"| node_audit_repo
node_access_service -->|"checks editor"| node_actor_repo
node_household_service -->|"loads apartment"| node_apartment_repo
node_household_service -->|"reads and writes"| node_household_repo
node_household_service -->|"resolves people"| node_person_repo
node_household_service -->|"checks residence"| node_resident_repo
node_household_service -->|"records changes"| node_history_repo
node_household_service -->|"records audit"| node_audit_repo
node_household_service -->|"resolves actor"| node_user_repo
node_details_service -->|"loads apartment"| node_apartment_repo
node_details_service -->|"loads active household"| node_household_repo
node_details_service -->|"checks residence"| node_resident_repo
node_details_service -->|"loads history"| node_history_repo
node_details_service -->|"finds person"| node_person_repo
node_apartment_repo -->|"persists apartments"| node_models
node_household_repo -->|"persists households"| node_models
node_resident_repo -->|"persists residents"| node_people
node_person_repo -->|"persists people"| node_people
node_history_repo -->|"persists history"| node_history_model
node_audit_repo -->|"persists audit"| node_audit_model
node_user_repo -->|"references user model"| node_people
node_models -.->|"stored via JPA"| node_database
node_people -.->|"stored via JPA"| node_database
node_history_model -.->|"stored via JPA"| node_database
node_audit_model -.->|"stored via JPA"| node_database

click node_mvc "https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/tree/main/src/main/java/com/bluemoon/bfms/controller"
click node_apartment_controller "https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/controller/ApartmentController.java"
click node_household_controller "https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/controller/HouseholdHeadController.java"
click node_apartment_service "https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/service/ApartmentService.java"
click node_access_service "https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/service/ApartmentAccessService.java"
click node_household_service "https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/service/HouseholdHeadService.java"
click node_details_service "https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/service/HouseholdDetailsService.java"
click node_apartment_repo "https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/repository/ApartmentRepository.java"
click node_household_repo "https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/repository/HouseholdRepository.java"
click node_resident_repo "https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/repository/ResidentRepository.java"
click node_person_repo "https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/repository/PersonRepository.java"
click node_history_repo "https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/repository/HouseholdHeadHistoryRepository.java"
click node_actor_repo "https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/repository/ApartmentActorRepository.java"
click node_user_repo "https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/repository/UserRepository.java"
click node_audit_repo "https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/repository/AuditLogRepository.java"
click node_models "https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/tree/main/src/main/java/com/bluemoon/bfms/model"
click node_people "https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/tree/main/src/main/java/com/bluemoon/bfms/model"
click node_history_model "https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/model/HouseholdHeadHistory.java"
click node_audit_model "https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/model/AuditLog.java"

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_mvc,node_apartment_controller,node_household_controller toneBlue
class node_apartment_service,node_access_service,node_household_service,node_details_service,node_database toneAmber
class node_apartment_repo,node_household_repo,node_resident_repo,node_person_repo,node_history_repo,node_actor_repo,node_user_repo,node_audit_repo toneMint
class node_models,node_people,node_history_model,node_audit_model toneRose
class node_administrator toneIndigo
```

## Components

### Web interface

- [Spring MVC](https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/tree/main/src/main/java/com/bluemoon/bfms/controller): `src/main/java/com/bluemoon/bfms/controller`
- [Apartment routes](https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/controller/ApartmentController.java): `src/main/java/com/bluemoon/bfms/controller/ApartmentController.java`
- [Household routes](https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/controller/HouseholdHeadController.java): `src/main/java/com/bluemoon/bfms/controller/HouseholdHeadController.java`

### Business services

- [Apartment management](https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/service/ApartmentService.java): `src/main/java/com/bluemoon/bfms/service/ApartmentService.java`
- [Apartment access](https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/service/ApartmentAccessService.java): `src/main/java/com/bluemoon/bfms/service/ApartmentAccessService.java`
- [Household-head changes](https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/service/HouseholdHeadService.java): `src/main/java/com/bluemoon/bfms/service/HouseholdHeadService.java`
- [Household details](https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/service/HouseholdDetailsService.java): `src/main/java/com/bluemoon/bfms/service/HouseholdDetailsService.java`

### Persistence

- [Apartment repository](https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/repository/ApartmentRepository.java): `src/main/java/com/bluemoon/bfms/repository/ApartmentRepository.java`
- [Household repository](https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/repository/HouseholdRepository.java): `src/main/java/com/bluemoon/bfms/repository/HouseholdRepository.java`
- [Resident repository](https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/repository/ResidentRepository.java): `src/main/java/com/bluemoon/bfms/repository/ResidentRepository.java`
- [Person repository](https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/repository/PersonRepository.java): `src/main/java/com/bluemoon/bfms/repository/PersonRepository.java`
- [Head-history repository](https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/repository/HouseholdHeadHistoryRepository.java): `src/main/java/com/bluemoon/bfms/repository/HouseholdHeadHistoryRepository.java`
- [Apartment actor repository](https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/repository/ApartmentActorRepository.java): `src/main/java/com/bluemoon/bfms/repository/ApartmentActorRepository.java`
- [User repository](https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/repository/UserRepository.java): `src/main/java/com/bluemoon/bfms/repository/UserRepository.java`
- [Audit repository](https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/repository/AuditLogRepository.java): `src/main/java/com/bluemoon/bfms/repository/AuditLogRepository.java`

### Domain data

- [Apartment and household entities](https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/tree/main/src/main/java/com/bluemoon/bfms/model): `src/main/java/com/bluemoon/bfms/model`
- [People and resident entities](https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/tree/main/src/main/java/com/bluemoon/bfms/model): `src/main/java/com/bluemoon/bfms/model`
- [Head-change history](https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/model/HouseholdHeadHistory.java): `src/main/java/com/bluemoon/bfms/model/HouseholdHeadHistory.java`
- [Audit log](https://github.com/cnpm-svbk-team13/bluemoon-apartment-management-system/blob/main/src/main/java/com/bluemoon/bfms/model/AuditLog.java): `src/main/java/com/bluemoon/bfms/model/AuditLog.java`

### Other components

- **Administrator**
- **PostgreSQL**

## Connections

- Administrator → Spring MVC: uses web app (evidence: `README.md`)
- Spring MVC → Apartment routes: routes requests
- Spring MVC → Household routes: routes requests
- Apartment routes → Apartment management: delegates to (evidence: `src/main/java/com/bluemoon/bfms/controller/ApartmentController.java`)
- Apartment routes → Apartment access: checks access (evidence: `src/main/java/com/bluemoon/bfms/controller/ApartmentController.java`)
- Household routes → Household-head changes: delegates to (evidence: `src/main/java/com/bluemoon/bfms/controller/HouseholdHeadController.java`)
- Household routes → Household details: loads details (evidence: `src/main/java/com/bluemoon/bfms/controller/HouseholdHeadController.java`)
- Apartment management → Apartment repository: reads and writes (evidence: `src/main/java/com/bluemoon/bfms/service/ApartmentService.java`)
- Apartment management → User repository: resolves actor (evidence: `src/main/java/com/bluemoon/bfms/service/ApartmentService.java`)
- Apartment management → Audit repository: records audit (evidence: `src/main/java/com/bluemoon/bfms/service/ApartmentService.java`)
- Apartment access → Apartment actor repository: checks editor (evidence: `src/main/java/com/bluemoon/bfms/service/ApartmentAccessService.java`)
- Household-head changes → Apartment repository: loads apartment (evidence: `src/main/java/com/bluemoon/bfms/service/HouseholdHeadService.java`)
- Household-head changes → Household repository: reads and writes (evidence: `src/main/java/com/bluemoon/bfms/service/HouseholdHeadService.java`)
- Household-head changes → Person repository: resolves people (evidence: `src/main/java/com/bluemoon/bfms/service/HouseholdHeadService.java`)
- Household-head changes → Resident repository: checks residence (evidence: `src/main/java/com/bluemoon/bfms/service/HouseholdHeadService.java`)
- Household-head changes → Head-history repository: records changes (evidence: `src/main/java/com/bluemoon/bfms/service/HouseholdHeadService.java`)
- Household-head changes → Audit repository: records audit (evidence: `src/main/java/com/bluemoon/bfms/service/HouseholdHeadService.java`)
- Household-head changes → User repository: resolves actor (evidence: `src/main/java/com/bluemoon/bfms/service/HouseholdHeadService.java`)
- Household details → Apartment repository: loads apartment (evidence: `src/main/java/com/bluemoon/bfms/service/HouseholdDetailsService.java`)
- Household details → Household repository: loads active household (evidence: `src/main/java/com/bluemoon/bfms/service/HouseholdDetailsService.java`)
- Household details → Resident repository: checks residence (evidence: `src/main/java/com/bluemoon/bfms/service/HouseholdDetailsService.java`)
- Household details → Head-history repository: loads history (evidence: `src/main/java/com/bluemoon/bfms/service/HouseholdDetailsService.java`)
- Household details → Person repository: finds person (evidence: `src/main/java/com/bluemoon/bfms/service/HouseholdDetailsService.java`)
- Apartment repository → Apartment and household entities: persists apartments (evidence: `src/main/java/com/bluemoon/bfms/repository/ApartmentRepository.java`)
- Household repository → Apartment and household entities: persists households (evidence: `src/main/java/com/bluemoon/bfms/repository/HouseholdRepository.java`)
- Resident repository → People and resident entities: persists residents (evidence: `src/main/java/com/bluemoon/bfms/repository/ResidentRepository.java`)
- Person repository → People and resident entities: persists people (evidence: `src/main/java/com/bluemoon/bfms/service/HouseholdDetailsService.java`)
- Head-history repository → Head-change history: persists history (evidence: `src/main/java/com/bluemoon/bfms/repository/HouseholdHeadHistoryRepository.java`)
- Audit repository → Audit log: persists audit (evidence: `src/main/java/com/bluemoon/bfms/service/ApartmentService.java`)
- User repository → People and resident entities: references user model (evidence: `src/main/java/com/bluemoon/bfms/repository/UserRepository.java`)
- Apartment and household entities → PostgreSQL: stored via JPA (evidence: `README.md`)
- People and resident entities → PostgreSQL: stored via JPA (evidence: `README.md`)
- Head-change history → PostgreSQL: stored via JPA (evidence: `README.md`)
- Audit log → PostgreSQL: stored via JPA (evidence: `README.md`)
