# azyzhm/unitrace-web-app architecture

> Architecture diagram of the GitHub repository azyzhm/unitrace-web-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/azyzhm/unitrace-web-app
- Repository: https://github.com/azyzhm/unitrace-web-app

## Overview

UniTrace is a university lost-and-found REST API: users register and verify accounts, publish lost/found declarations with optional pictures, manage declaration visibility and lifecycle, and maintain their profiles and sessions. HTTP requests enter through routes and controllers, which delegate business rules to services; repositories persist state through Mongoose. The README identifies search, matching, expiry automation, and admin endpoints as not yet implemented, so they are not represented as runtime components. Relationships below are limited to README or excerpt/Source Index evidence; unsampled subsystem links are omitted where callers are not shown.

Main entry points: [`backend/src/routes/index.js`](https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/routes/index.js) (API routes), [`backend/src/services/auth`](https://github.com/azyzhm/unitrace-web-app/tree/main/backend/src/services/auth) (Auth & session), [`backend/src/controllers/declarations/declaration.controller.js`](https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/controllers/declarations/declaration.controller.js) (Declaration controller), [`backend/src/app.js`](https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/app.js) (HTTP application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP API"]
  node_server["Server startup<br/>[server.js]"]
  node_app["HTTP application<br/>[app.js]"]
  node_routes["API routes<br/>[index.js]"]
  node_authroutes["Auth routes<br/>[auth.routes.js]"]
  node_userroutes["User routes<br/>[user.routes.js]"]
  node_declroutes["Declaration routes"]
  node_errorhandler["Error response<br/>[error-handler.js]"]
end

subgraph group_identity["Identity &amp; Accounts"]
  node_authcontroller["Auth controller<br/>[auth.controller.js]"]
  node_usercontroller["User controller<br/>[user.controller.js]"]
  node_authservices["Auth &amp; session"]
  node_profiles["Profile &amp; deletion"]
  node_userpresenter["User presenter<br/>[user.presenter.js]"]
end

subgraph group_declarations["Declarations"]
  node_declcontroller["Declaration controller"]
  node_declservice["Declaration rules"]
  node_picture["Picture handling<br/>[picture-storage.js]"]
  node_declpresenter["Declaration presenter"]
end

subgraph group_persistence["Persistence &amp; Events"]
  node_mongo[("MongoDB")]
  node_declrepo["Declaration repository"]
  node_userrepo["User repository<br/>[user.repository.js]"]
  node_authrepo["Auth repositories"]
  node_eventbus["Event bus<br/>[event-bus.js]"]
end

subgraph group_integrations["External Services"]
  node_mailer["Email delivery<br/>[email.service.js]"]
  node_agentmail["AgentMail"]
end

node_caller(("API client"))

node_caller -->|"sends requests"| node_app
node_server -->|"starts"| node_app
node_app -->|"mounts routes"| node_routes
node_routes -->|"registers"| node_authroutes
node_routes -->|"registers"| node_userroutes
node_routes -->|"registers"| node_declroutes
node_authroutes -->|"dispatches"| node_authcontroller
node_userroutes -->|"dispatches"| node_usercontroller
node_declroutes -->|"dispatches"| node_declcontroller
node_authcontroller -->|"delegates"| node_authservices
node_usercontroller -->|"delegates"| node_profiles
node_declcontroller -->|"delegates"| node_declservice
node_authcontroller -->|"formats users"| node_userpresenter
node_usercontroller -->|"formats users"| node_userpresenter
node_declcontroller -->|"formats declarations"| node_declpresenter
node_declservice -->|"queries"| node_declrepo
node_declcontroller -.->|"serves picture"| node_picture
node_declrepo -->|"reads and writes"| node_mongo
node_authservices -.->|"accesses users"| node_userrepo
node_authservices -.->|"manages tokens"| node_authrepo
node_profiles -.->|"accesses users"| node_userrepo
node_authrepo -.->|"persists auth"| node_mongo
node_userrepo -.->|"persists users"| node_mongo
node_authservices -->|"sends codes"| node_mailer
node_profiles -->|"sends codes"| node_mailer
node_mailer -->|"sends email"| node_agentmail
node_app -->|"handles errors"| node_errorhandler
node_server -->|"registers listener"| node_eventbus
node_declservice -.->|"emits events"| node_eventbus

click node_server "https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/server.js"
click node_app "https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/app.js"
click node_routes "https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/routes/index.js"
click node_authroutes "https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/routes/auth/auth.routes.js"
click node_userroutes "https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/routes/users/user.routes.js"
click node_declroutes "https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/routes/declarations/declaration.routes.js"
click node_authcontroller "https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/controllers/auth/auth.controller.js"
click node_usercontroller "https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/controllers/users/user.controller.js"
click node_authservices "https://github.com/azyzhm/unitrace-web-app/tree/main/backend/src/services/auth"
click node_profiles "https://github.com/azyzhm/unitrace-web-app/tree/main/backend/src/services/users"
click node_userpresenter "https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/presenters/users/user.presenter.js"
click node_declcontroller "https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/controllers/declarations/declaration.controller.js"
click node_declservice "https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/services/declarations/declaration.service.js"
click node_picture "https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/services/declarations/picture-storage.js"
click node_declpresenter "https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/presenters/declarations/declaration.presenter.js"
click node_declrepo "https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/repositories/declarations/declaration.repository.js"
click node_userrepo "https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/repositories/users/user.repository.js"
click node_authrepo "https://github.com/azyzhm/unitrace-web-app/tree/main/backend/src/repositories/auth"
click node_eventbus "https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/events/common/event-bus.js"
click node_mailer "https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/services/common/email.service.js"
click node_errorhandler "https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/middlewares/common/error-handler.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_server,node_app,node_routes,node_authroutes,node_userroutes,node_declroutes,node_errorhandler,node_caller toneBlue
class node_authcontroller,node_usercontroller,node_authservices,node_profiles,node_userpresenter toneAmber
class node_declcontroller,node_declservice,node_picture,node_declpresenter toneMint
class node_mongo,node_declrepo,node_userrepo,node_authrepo,node_eventbus toneRose
class node_mailer,node_agentmail toneIndigo
```

## Components

### HTTP API

- [Server startup](https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/server.js): `backend/src/server.js`
- [HTTP application](https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/app.js): `backend/src/app.js`
- [API routes](https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/routes/index.js): `backend/src/routes/index.js`
- [Auth routes](https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/routes/auth/auth.routes.js): `backend/src/routes/auth/auth.routes.js`
- [User routes](https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/routes/users/user.routes.js): `backend/src/routes/users/user.routes.js`
- [Declaration routes](https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/routes/declarations/declaration.routes.js): `backend/src/routes/declarations/declaration.routes.js`
- [Error response](https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/middlewares/common/error-handler.js): `backend/src/middlewares/common/error-handler.js`

### Identity & Accounts

- [Auth controller](https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/controllers/auth/auth.controller.js): `backend/src/controllers/auth/auth.controller.js`
- [User controller](https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/controllers/users/user.controller.js): `backend/src/controllers/users/user.controller.js`
- [Auth & session](https://github.com/azyzhm/unitrace-web-app/tree/main/backend/src/services/auth): `backend/src/services/auth`
- [Profile & deletion](https://github.com/azyzhm/unitrace-web-app/tree/main/backend/src/services/users): `backend/src/services/users`
- [User presenter](https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/presenters/users/user.presenter.js): `backend/src/presenters/users/user.presenter.js`

### Declarations

- [Declaration controller](https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/controllers/declarations/declaration.controller.js): `backend/src/controllers/declarations/declaration.controller.js`
- [Declaration rules](https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/services/declarations/declaration.service.js): `backend/src/services/declarations/declaration.service.js`
- [Picture handling](https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/services/declarations/picture-storage.js): `backend/src/services/declarations/picture-storage.js`
- [Declaration presenter](https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/presenters/declarations/declaration.presenter.js): `backend/src/presenters/declarations/declaration.presenter.js`

### Persistence & Events

- **MongoDB**
- [Declaration repository](https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/repositories/declarations/declaration.repository.js): `backend/src/repositories/declarations/declaration.repository.js`
- [User repository](https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/repositories/users/user.repository.js): `backend/src/repositories/users/user.repository.js`
- [Auth repositories](https://github.com/azyzhm/unitrace-web-app/tree/main/backend/src/repositories/auth): `backend/src/repositories/auth`
- [Event bus](https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/events/common/event-bus.js): `backend/src/events/common/event-bus.js`

### External Services

- [Email delivery](https://github.com/azyzhm/unitrace-web-app/blob/main/backend/src/services/common/email.service.js): `backend/src/services/common/email.service.js`
- **AgentMail**

### Other components

- **API client**

## Connections

- API client → HTTP application: sends requests (evidence: `README.md`)
- Server startup → HTTP application: starts (evidence: `backend/src/server.js`)
- HTTP application → API routes: mounts routes (evidence: `backend/src/app.js`)
- API routes → Auth routes: registers (evidence: `backend/src/routes/index.js`)
- API routes → User routes: registers (evidence: `backend/src/routes/index.js`)
- API routes → Declaration routes: registers (evidence: `backend/src/routes/index.js`)
- Auth routes → Auth controller: dispatches (evidence: `backend/src/routes/auth/auth.routes.js`)
- User routes → User controller: dispatches (evidence: `backend/src/routes/users/user.routes.js`)
- Declaration routes → Declaration controller: dispatches (evidence: `backend/src/routes/declarations/declaration.routes.js`)
- Auth controller → Auth & session: delegates (evidence: `backend/src/controllers/auth/auth.controller.js`)
- User controller → Profile & deletion: delegates (evidence: `backend/src/controllers/users/user.controller.js`)
- Declaration controller → Declaration rules: delegates (evidence: `backend/src/controllers/declarations/declaration.controller.js`)
- Auth controller → User presenter: formats users (evidence: `backend/src/controllers/auth/auth.controller.js`)
- User controller → User presenter: formats users (evidence: `backend/src/controllers/users/user.controller.js`)
- Declaration controller → Declaration presenter: formats declarations (evidence: `backend/src/controllers/declarations/declaration.controller.js`)
- Declaration rules → Declaration repository: queries (evidence: `backend/src/services/declarations/declaration.service.js`)
- Declaration controller → Picture handling: serves picture
- Declaration repository → MongoDB: reads and writes (evidence: `backend/src/repositories/declarations/declaration.repository.js`)
- Auth & session → User repository: accesses users
- Auth & session → Auth repositories: manages tokens
- Profile & deletion → User repository: accesses users
- Auth repositories → MongoDB: persists auth
- User repository → MongoDB: persists users
- Auth & session → Email delivery: sends codes (evidence: `backend/src/services/auth/auth.service.js`)
- Profile & deletion → Email delivery: sends codes (evidence: `backend/src/services/users/profile.service.js`)
- Email delivery → AgentMail: sends email (evidence: `backend/src/services/common/email.service.js`)
- HTTP application → Error response: handles errors (evidence: `backend/src/app.js`)
- Server startup → Event bus: registers listener (evidence: `backend/src/server.js`)
- Declaration rules → Event bus: emits events