# tejasrp24/dbms_proj_backend architecture

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

- Interactive diagram: https://gitdiagram.com/tejasrp24/dbms_proj_backend
- Repository: https://github.com/tejasrp24/dbms_proj_backend

## Overview

#### Purpose and entry points
AG-OS is a cognitive-memory assistant for users with short-term memory loss. It combines camera-based face recognition, recorded-audio transcription, LLM-generated interaction summaries, persistent memory, and reminders/calendar data. The documented production API entry point is `app/services/face_recognition/main.py`; an alternate/duplicated backend layout also exposes `backend/app/main.py`. The React/Vite client starts at `frontend/src/main.jsx` and renders `frontend/src/App.jsx`.

#### HTTP/API boundary
FastAPI routes organize the core domain API: people, caregivers, sessions, interactions, memory, notes, emotions, audio, and calendar events. Route handlers validate request/response payloads through schemas and delegate domain work to services. Key paths: `app/api/routes/persons.py`, `app/api/routes/interactions.py`, `app/api/routes/memory.py`, `app/schemas/interaction.py`.

#### Persistence and domain model
PostgreSQL is the system of record, configured through application database/session modules. SQLAlchemy-style domain models represent users, known persons, caregivers, conversations, face encodings, notes, emotional records, and calendar events; association tables encode relationships. Paths: `app/db/session.py`, `app/models/person.py`, `app/models/conversation.py`, `app/models/junction_tables.py`. A separate SQL schema exists at `database/schema.sql`, indicating possible legacy/direct-SQL persistence alongside the ORM-oriented structure.

#### Recognition and interaction pipeline
The primary assistant flow is camera input → face detection/recognition → person identity or unknown-person handling → interaction creation and memory context. Recognition is isolated behind the face-recognition service and controllers, using bundled OpenCV/Caffe and YOLO assets. Paths: `app/services/face_recognition/main.py`, `app/services/face_recognition/face_service.py`, `app/controllers/face_controller.py`, `app/models/face_encoding.py`. Material ML assets include `yolov8n.pt`, `deploy.prototxt`, and `res10_300x300_ssd_iter_140000.caffemodel`.

#### Audio, transcription, and summarization
Audio endpoints/controllers accept or manage recordings, then invoke Whisper/faster-whisper transcription. Interaction and conversation services combine transcripts, recognized-person context, and stored memory; the LLM layer produces summaries or assistant output. Paths: `app/api/routes/audio.py`, `app/controllers/audio_controller.py`, `app/services/whisper_service.py`, `app/services/conversation_summarizer.py`, `app/services/llm_service.py`. LLM providers are runtime-selectable: Groq by default, with OpenAI and local Ollama options.

#### Memory and care workflows
Dedicated services maintain long-lived memory, notes, emotional observations, caregiver relationships, and calendar events. This separates medical/care context from transient recognition and transcription requests. Paths: `app/services/memory_service.py`, `app/services/note_service.py`, `app/services/emotion_service.py`, `app/services/caregiver_service.py`, `app/services/calendar_service.py`.

#### Reminders, scheduling, and external integrations
APScheduler supports scheduled application work, while a Celery-oriented reminders subsystem provides asynchronous reminder tasks. Google Calendar and Google Tasks integrations form an external authorization/API boundary. Paths: `app/core/scheduler.py`, `app/ai_models/reminders/tasks.py`, `app/ai_models/reminders/celery_config.py`, `app/services/google_calendar.py`, `app/services/google_tasks.py`.

#### Runtime and repository shape
The intended runtime is Python 3.11/FastAPI on port 8004 plus a Node 18 React/Vite frontend on port 5173; Docker support is rooted at `Dockerfile`. PostgreSQL may be local or Neon-hosted. The repository contains overlapping `app/` and `backend/app/` implementations; use the README’s `app/services/face_recognition/main.py` entry point unless deployment wiring explicitly targets `backend/run.py`.

Main entry points: [`app/api/routes/interactions.py`](https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/api/routes/interactions.py) (Domain routes), [`app/services/memory_service.py`](https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/services/memory_service.py) (Care services), [`app/services/conversation_summarizer.py`](https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/services/conversation_summarizer.py) (Conversation AI), [`app/services/face_recognition/main.py`](https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/services/face_recognition/main.py) (Production API entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_frontend["React/Vite client<br/>frontend<br/>[main.jsx]"]
  node_app_ui["App UI<br/>React application<br/>[App.jsx]"]
end

subgraph group_api["FastAPI application"]
  node_face_entry["Production API entry<br/>FastAPI entry point<br/>[main.py]"]
  node_alternate_backend["Alternate backend<br/>duplicated API entry<br/>[main.py]"]
  node_domain_routes["Domain routes<br/>FastAPI routes<br/>[interactions.py]"]
  node_audio_routes["Audio routes<br/>FastAPI routes<br/>[audio.py]"]
  node_interaction_schema["Interaction schemas<br/>request/response schemas<br/>[interaction.py]"]
end

subgraph group_intelligence["Recognition &amp; AI"]
  node_face_controller["Face controller<br/>recognition controller<br/>[face_controller.py]"]
  node_face_service["Face recognition<br/>vision service<br/>[face_service.py]"]
  node_face_encoding["Face encodings<br/>domain model<br/>[face_encoding.py]"]
  node_audio_controller["Audio controller<br/>audio workflow"]
  node_whisper["Transcription<br/>Whisper service<br/>[whisper_service.py]"]
  node_conversation_ai["Conversation AI<br/>summarization service"]
  node_llm["LLM providers<br/>LLM service<br/>[llm_service.py]"]
end

subgraph group_care["Memory &amp; care"]
  node_care_services["Care services<br/>memory and care domain<br/>[memory_service.py]"]
  node_postgres[("PostgreSQL<br/>system of record<br/>[session.py]")]
  node_domain_models["Domain models<br/>SQLAlchemy models<br/>[person.py]"]
end

subgraph group_async["Scheduling &amp; integrations"]
  node_scheduler["Scheduler<br/>[scheduler.py]"]
  node_reminder_tasks["Reminder workers<br/>Celery tasks<br/>[tasks.py]"]
  node_google_calendar["Google integrations<br/>Calendar and Tasks APIs<br/>[google_calendar.py]"]
end

node_frontend -->|"renders"| node_app_ui
node_app_ui -->|"HTTP API"| node_face_entry
node_face_entry -->|"serves"| node_domain_routes
node_face_entry -->|"serves"| node_audio_routes
node_alternate_backend -.->|"alternate layout"| node_domain_routes
node_domain_routes -->|"validates"| node_interaction_schema
node_domain_routes -->|"recognition requests"| node_face_controller
node_face_controller -->|"detects and identifies"| node_face_service
node_face_service -->|"matches"| node_face_encoding
node_audio_routes -->|"recordings"| node_audio_controller
node_audio_controller -->|"transcribes"| node_whisper
node_whisper -->|"transcript"| node_conversation_ai
node_face_controller -->|"person context"| node_conversation_ai
node_conversation_ai -->|"generates summary"| node_llm
node_domain_routes -->|"care operations"| node_care_services
node_care_services -->|"persists"| node_postgres
node_domain_models -->|"maps records"| node_postgres
node_face_encoding -->|"stored in"| node_postgres
node_conversation_ai -->|"memory context"| node_care_services
node_scheduler -->|"triggers"| node_reminder_tasks
node_reminder_tasks -->|"reads reminders"| node_care_services
node_care_services -->|"syncs events"| node_google_calendar

click node_frontend "https://github.com/tejasrp24/dbms_proj_backend/blob/main/frontend/src/main.jsx"
click node_app_ui "https://github.com/tejasrp24/dbms_proj_backend/blob/main/frontend/src/App.jsx"
click node_face_entry "https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/services/face_recognition/main.py"
click node_alternate_backend "https://github.com/tejasrp24/dbms_proj_backend/blob/main/backend/app/main.py"
click node_domain_routes "https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/api/routes/interactions.py"
click node_audio_routes "https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/api/routes/audio.py"
click node_interaction_schema "https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/schemas/interaction.py"
click node_face_controller "https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/controllers/face_controller.py"
click node_face_service "https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/services/face_recognition/face_service.py"
click node_face_encoding "https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/models/face_encoding.py"
click node_audio_controller "https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/controllers/audio_controller.py"
click node_whisper "https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/services/whisper_service.py"
click node_conversation_ai "https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/services/conversation_summarizer.py"
click node_llm "https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/services/llm_service.py"
click node_care_services "https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/services/memory_service.py"
click node_postgres "https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/db/session.py"
click node_domain_models "https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/models/person.py"
click node_scheduler "https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/core/scheduler.py"
click node_reminder_tasks "https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/ai_models/reminders/tasks.py"
click node_google_calendar "https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/services/google_calendar.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_frontend,node_app_ui toneBlue
class node_face_entry,node_alternate_backend,node_domain_routes,node_audio_routes,node_interaction_schema toneAmber
class node_face_controller,node_face_service,node_face_encoding,node_audio_controller,node_whisper,node_conversation_ai,node_llm toneMint
class node_care_services,node_postgres,node_domain_models toneRose
class node_scheduler,node_reminder_tasks,node_google_calendar toneIndigo
```

## Components

### Client

- [React/Vite client](https://github.com/tejasrp24/dbms_proj_backend/blob/main/frontend/src/main.jsx): frontend · `frontend/src/main.jsx`
- [App UI](https://github.com/tejasrp24/dbms_proj_backend/blob/main/frontend/src/App.jsx): React application · `frontend/src/App.jsx`

### FastAPI application

- [Production API entry](https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/services/face_recognition/main.py): FastAPI entry point · Documented production server entry point. · `app/services/face_recognition/main.py`
- [Alternate backend](https://github.com/tejasrp24/dbms_proj_backend/blob/main/backend/app/main.py): duplicated API entry · Overlapping backend implementation. · `backend/app/main.py`
- [Domain routes](https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/api/routes/interactions.py): FastAPI routes · People, sessions, interactions, memory, audio, and calendar APIs. · `app/api/routes/interactions.py`
- [Audio routes](https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/api/routes/audio.py): FastAPI routes · `app/api/routes/audio.py`
- [Interaction schemas](https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/schemas/interaction.py): request/response schemas · `app/schemas/interaction.py`

### Recognition & AI

- [Face controller](https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/controllers/face_controller.py): recognition controller · `app/controllers/face_controller.py`
- [Face recognition](https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/services/face_recognition/face_service.py): vision service · Detects and recognizes faces using bundled ML assets. · `app/services/face_recognition/face_service.py`
- [Face encodings](https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/models/face_encoding.py): domain model · `app/models/face_encoding.py`
- [Audio controller](https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/controllers/audio_controller.py): audio workflow · `app/controllers/audio_controller.py`
- [Transcription](https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/services/whisper_service.py): Whisper service · `app/services/whisper_service.py`
- [Conversation AI](https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/services/conversation_summarizer.py): summarization service · Combines transcript, identity, and memory context. · `app/services/conversation_summarizer.py`
- [LLM providers](https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/services/llm_service.py): LLM service · Selects Groq, OpenAI, or local Ollama at runtime. · `app/services/llm_service.py`

### Memory & care

- [Care services](https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/services/memory_service.py): memory and care domain · Maintains memory, notes, emotions, caregivers, and events. · `app/services/memory_service.py`
- [PostgreSQL](https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/db/session.py): system of record · Stores ORM domain records and relationships. · `app/db/session.py`
- [Domain models](https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/models/person.py): SQLAlchemy models · People, conversations, and relationship associations. · `app/models/person.py`

### Scheduling & integrations

- [Scheduler](https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/core/scheduler.py): APScheduler · `app/core/scheduler.py`
- [Reminder workers](https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/ai_models/reminders/tasks.py): Celery tasks · `app/ai_models/reminders/tasks.py`
- [Google integrations](https://github.com/tejasrp24/dbms_proj_backend/blob/main/app/services/google_calendar.py): Calendar and Tasks APIs · External authorization and calendar/task boundary. · `app/services/google_calendar.py`

## Connections

- React/Vite client → App UI: renders
- App UI → Production API entry: HTTP API
- Production API entry → Domain routes: serves
- Production API entry → Audio routes: serves
- Alternate backend → Domain routes: alternate layout
- Domain routes → Interaction schemas: validates
- Domain routes → Face controller: recognition requests
- Face controller → Face recognition: detects and identifies
- Face recognition → Face encodings: matches
- Audio routes → Audio controller: recordings
- Audio controller → Transcription: transcribes
- Transcription → Conversation AI: transcript
- Face controller → Conversation AI: person context
- Conversation AI → LLM providers: generates summary
- Domain routes → Care services: care operations
- Care services → PostgreSQL: persists
- Domain models → PostgreSQL: maps records
- Face encodings → PostgreSQL: stored in
- Conversation AI → Care services: memory context
- Scheduler → Reminder workers: triggers
- Reminder workers → Care services: reads reminders
- Care services → Google integrations: syncs events