# isaias-morais/atlas0.1 architecture

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

- Interactive diagram: https://gitdiagram.com/isaias-morais/atlas0.1
- Repository: https://github.com/isaias-morais/atlas0.1

## Overview

ATLAS is a web-based personal assistant: users enter text or voice commands, the API interprets them, dispatches known command types to services, and returns results that the frontend can act on. Separate API paths support login, user management, and reminder CRUD. The README also describes a future AI path, but the sampled evidence does not establish how it connects to command dispatch; the AI and music capabilities are therefore shown as distinct, with uncertain integration omitted.

Main entry points: [`backend/app/routes/command_routes.py`](https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/routes/command_routes.py) (Command endpoint), [`backend/app/main.py`](https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/main.py) (FastAPI application), [`backend/app/database/connection.py`](https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/database/connection.py) (Database sessions), [`frontend/js/script.js`](https://github.com/isaias-morais/atlas0.1/blob/master/frontend/js/script.js) (Web interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web interface"]
  node_frontend["Web interface<br/>[script.js]"]
  node_voice["Voice input<br/>[voice.js]"]
  node_login_ui["Login client<br/>[login.js]"]
  node_auth_client["Auth client<br/>[auth.js]"]
  node_api_client["Command client<br/>[api.js]"]
  node_music_ui["Music playback<br/>[music.js]"]
end

subgraph group_api["API and identity"]
  node_app["FastAPI application<br/>[main.py]"]
  node_auth_routes["Auth routes<br/>[auth_routes.py]"]
  node_user_routes["User routes<br/>[user_routes.py]"]
  node_reminder_routes["Reminder routes<br/>[reminder_routes.py]"]
  node_security["Token validation<br/>[auth.py]"]
  node_auth_service["Login service<br/>[auth_service.py]"]
end

subgraph group_commands["Command handling"]
  node_command_routes["Command endpoint<br/>[command_routes.py]"]
  node_interpreter["Command interpreter<br/>[interpreter.py]"]
  node_dispatcher["Command dispatcher<br/>[dispatcher.py]"]
  node_schemas["Request schemas<br/>[command_scherma.py]"]
end

subgraph group_features["Assistant features"]
  node_reminder_service["Reminder service"]
  node_user_service["User service<br/>[user_service.py]"]
  node_music_service["Music service<br/>[music_service.py]"]
  node_youtube["YouTube provider"]
  node_ai_service["AI service<br/>[ai_service.py]"]
  node_ai_router["AI provider router<br/>[router.py]"]
  node_ai_base["AI provider interface<br/>[base.py]"]
  node_ai_fake["Fake AI provider<br/>[fake.py]"]
end

subgraph group_data["Persistence"]
  node_connection["Database sessions<br/>[connection.py]"]
  node_base["ORM metadata<br/>[base.py]"]
  node_users[("User records<br/>[user.py]")]
  node_reminders[("Reminder records<br/>[reminder.py]")]
  node_user_repo["User repository<br/>[user_repository.py]"]
  node_reminder_repo["Reminder repository"]
end

node_user(("Assistant user"))

node_user -->|"uses"| node_frontend
node_frontend -->|"captures speech"| node_voice
node_frontend -->|"submits commands"| node_api_client
node_frontend -->|"uses login"| node_auth_client
node_login_ui -->|"calls login"| node_auth_client
node_voice -->|"sends text"| node_api_client
node_api_client -->|"plays music"| node_music_ui
node_api_client -->|"HTTP command"| node_command_routes
node_auth_client -->|"HTTP login"| node_auth_routes
node_app -->|"registers"| node_auth_routes
node_app -->|"registers"| node_command_routes
node_app -->|"registers"| node_user_routes
node_app -->|"registers"| node_reminder_routes
node_command_routes -->|"interprets text"| node_interpreter
node_command_routes -->|"dispatches command"| node_dispatcher
node_command_routes -->|"authenticates"| node_security
node_command_routes -->|"gets session"| node_connection
node_interpreter -->|"produces command"| node_schemas
node_dispatcher -->|"uses command types"| node_schemas
node_dispatcher -->|"handles music"| node_music_service
node_dispatcher -->|"handles reminders"| node_reminder_service
node_music_service -->|"uses provider"| node_youtube
node_reminder_routes -->|"calls CRUD"| node_reminder_service
node_reminder_routes -->|"authenticates"| node_security
node_reminder_routes -->|"gets session"| node_connection
node_user_routes -->|"calls CRUD"| node_user_service
node_user_routes -->|"gets session"| node_connection
node_auth_routes -->|"calls login"| node_auth_service
node_auth_service -->|"finds user"| node_user_repo
node_user_service -->|"uses repository"| node_user_repo
node_reminder_service -->|"uses repository"| node_reminder_repo
node_reminder_service -->|"checks owner"| node_user_repo
node_user_repo -->|"queries records"| node_users
node_reminder_repo -->|"queries records"| node_reminders
node_users -->|"maps ORM"| node_base
node_reminders -->|"maps ORM"| node_base
node_app -->|"creates schema"| node_connection
node_connection -.->|"binds metadata"| node_base
node_ai_service -->|"uses interface"| node_ai_base
node_ai_fake -->|"implements provider"| node_ai_base
node_ai_router -.->|"provider routing"| node_ai_base

click node_frontend "https://github.com/isaias-morais/atlas0.1/blob/master/frontend/js/script.js"
click node_voice "https://github.com/isaias-morais/atlas0.1/blob/master/frontend/js/voice.js"
click node_login_ui "https://github.com/isaias-morais/atlas0.1/blob/master/frontend/js/login.js"
click node_auth_client "https://github.com/isaias-morais/atlas0.1/blob/master/frontend/js/auth.js"
click node_api_client "https://github.com/isaias-morais/atlas0.1/blob/master/frontend/js/api.js"
click node_music_ui "https://github.com/isaias-morais/atlas0.1/blob/master/frontend/js/music.js"
click node_app "https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/main.py"
click node_auth_routes "https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/routes/auth_routes.py"
click node_user_routes "https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/routes/user_routes.py"
click node_reminder_routes "https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/routes/reminder_routes.py"
click node_security "https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/security/auth.py"
click node_auth_service "https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/services/auth_service.py"
click node_command_routes "https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/routes/command_routes.py"
click node_interpreter "https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/interpreter/interpreter.py"
click node_dispatcher "https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/dispatcher/dispatcher.py"
click node_schemas "https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/schemas/command_scherma.py"
click node_reminder_service "https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/services/reminder_service.py"
click node_user_service "https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/services/user_service.py"
click node_music_service "https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/services/music_service.py"
click node_youtube "https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/providers/youtube_provider.py"
click node_ai_service "https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/services/ai_service.py"
click node_ai_router "https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/ai/router.py"
click node_ai_base "https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/ai/providers/base.py"
click node_ai_fake "https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/ai/providers/fake.py"
click node_connection "https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/database/connection.py"
click node_base "https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/database/base.py"
click node_users "https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/models/user.py"
click node_reminders "https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/models/reminder.py"
click node_user_repo "https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/repositories/user_repository.py"
click node_reminder_repo "https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/repositories/reminder_repository.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_voice,node_login_ui,node_auth_client,node_api_client,node_music_ui,node_user toneBlue
class node_app,node_auth_routes,node_user_routes,node_reminder_routes,node_security,node_auth_service toneAmber
class node_command_routes,node_interpreter,node_dispatcher,node_schemas toneMint
class node_reminder_service,node_user_service,node_music_service,node_youtube,node_ai_service,node_ai_router,node_ai_base,node_ai_fake toneRose
class node_connection,node_base,node_users,node_reminders,node_user_repo,node_reminder_repo toneIndigo
```

## Components

### Web interface

- [Web interface](https://github.com/isaias-morais/atlas0.1/blob/master/frontend/js/script.js): `frontend/js/script.js`
- [Voice input](https://github.com/isaias-morais/atlas0.1/blob/master/frontend/js/voice.js): `frontend/js/voice.js`
- [Login client](https://github.com/isaias-morais/atlas0.1/blob/master/frontend/js/login.js): `frontend/js/login.js`
- [Auth client](https://github.com/isaias-morais/atlas0.1/blob/master/frontend/js/auth.js): `frontend/js/auth.js`
- [Command client](https://github.com/isaias-morais/atlas0.1/blob/master/frontend/js/api.js): `frontend/js/api.js`
- [Music playback](https://github.com/isaias-morais/atlas0.1/blob/master/frontend/js/music.js): `frontend/js/music.js`

### API and identity

- [FastAPI application](https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/main.py): `backend/app/main.py`
- [Auth routes](https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/routes/auth_routes.py): `backend/app/routes/auth_routes.py`
- [User routes](https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/routes/user_routes.py): `backend/app/routes/user_routes.py`
- [Reminder routes](https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/routes/reminder_routes.py): `backend/app/routes/reminder_routes.py`
- [Token validation](https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/security/auth.py): `backend/app/security/auth.py`
- [Login service](https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`

### Command handling

- [Command endpoint](https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/routes/command_routes.py): `backend/app/routes/command_routes.py`
- [Command interpreter](https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/interpreter/interpreter.py): `backend/app/interpreter/interpreter.py`
- [Command dispatcher](https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/dispatcher/dispatcher.py): `backend/app/dispatcher/dispatcher.py`
- [Request schemas](https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/schemas/command_scherma.py): `backend/app/schemas/command_scherma.py`

### Assistant features

- [Reminder service](https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/services/reminder_service.py): `backend/app/services/reminder_service.py`
- [User service](https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/services/user_service.py): `backend/app/services/user_service.py`
- [Music service](https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/services/music_service.py): `backend/app/services/music_service.py`
- [YouTube provider](https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/providers/youtube_provider.py): `backend/app/providers/youtube_provider.py`
- [AI service](https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/services/ai_service.py): `backend/app/services/ai_service.py`
- [AI provider router](https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/ai/router.py): `backend/app/ai/router.py`
- [AI provider interface](https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/ai/providers/base.py): `backend/app/ai/providers/base.py`
- [Fake AI provider](https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/ai/providers/fake.py): `backend/app/ai/providers/fake.py`

### Persistence

- [Database sessions](https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/database/connection.py): `backend/app/database/connection.py`
- [ORM metadata](https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/database/base.py): `backend/app/database/base.py`
- [User records](https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/models/user.py): `backend/app/models/user.py`
- [Reminder records](https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/models/reminder.py): `backend/app/models/reminder.py`
- [User repository](https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/repositories/user_repository.py): `backend/app/repositories/user_repository.py`
- [Reminder repository](https://github.com/isaias-morais/atlas0.1/blob/master/backend/app/repositories/reminder_repository.py): `backend/app/repositories/reminder_repository.py`

### Other components

- **Assistant user**

## Connections

- Assistant user → Web interface: uses
- Web interface → Voice input: captures speech (evidence: `frontend/js/script.js`)
- Web interface → Command client: submits commands (evidence: `frontend/js/script.js`)
- Web interface → Auth client: uses login (evidence: `frontend/js/script.js`)
- Login client → Auth client: calls login (evidence: `frontend/js/login.js`)
- Voice input → Command client: sends text (evidence: `frontend/js/voice.js`)
- Command client → Music playback: plays music (evidence: `frontend/js/api.js`)
- Command client → Command endpoint: HTTP command (evidence: `frontend/js/api.js`)
- Auth client → Auth routes: HTTP login (evidence: `frontend/js/auth.js`)
- FastAPI application → Auth routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Command endpoint: registers (evidence: `backend/app/main.py`)
- FastAPI application → User routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Reminder routes: registers (evidence: `backend/app/main.py`)
- Command endpoint → Command interpreter: interprets text (evidence: `backend/app/routes/command_routes.py`)
- Command endpoint → Command dispatcher: dispatches command (evidence: `backend/app/routes/command_routes.py`)
- Command endpoint → Token validation: authenticates (evidence: `backend/app/routes/command_routes.py`)
- Command endpoint → Database sessions: gets session (evidence: `backend/app/routes/command_routes.py`)
- Command interpreter → Request schemas: produces command (evidence: `backend/app/interpreter/interpreter.py`)
- Command dispatcher → Request schemas: uses command types (evidence: `backend/app/dispatcher/dispatcher.py`)
- Command dispatcher → Music service: handles music (evidence: `backend/app/dispatcher/dispatcher.py`)
- Command dispatcher → Reminder service: handles reminders (evidence: `backend/app/dispatcher/dispatcher.py`)
- Music service → YouTube provider: uses provider (evidence: `backend/app/services/music_service.py`)
- Reminder routes → Reminder service: calls CRUD (evidence: `backend/app/routes/reminder_routes.py`)
- Reminder routes → Token validation: authenticates (evidence: `backend/app/routes/reminder_routes.py`)
- Reminder routes → Database sessions: gets session (evidence: `backend/app/routes/reminder_routes.py`)
- User routes → User service: calls CRUD (evidence: `backend/app/routes/user_routes.py`)
- User routes → Database sessions: gets session (evidence: `backend/app/routes/user_routes.py`)
- Auth routes → Login service: calls login (evidence: `backend/app/routes/auth_routes.py`)
- Login service → User repository: finds user (evidence: `backend/app/services/auth_service.py`)
- User service → User repository: uses repository (evidence: `backend/app/services/user_service.py`)
- Reminder service → Reminder repository: uses repository (evidence: `backend/app/services/reminder_service.py`)
- Reminder service → User repository: checks owner (evidence: `backend/app/services/reminder_service.py`)
- User repository → User records: queries records (evidence: `backend/app/repositories/user_repository.py`)
- Reminder repository → Reminder records: queries records (evidence: `backend/app/repositories/reminder_repository.py`)
- User records → ORM metadata: maps ORM (evidence: `backend/app/models/user.py`)
- Reminder records → ORM metadata: maps ORM (evidence: `backend/app/models/reminder.py`)
- FastAPI application → Database sessions: creates schema (evidence: `backend/app/main.py`)
- Database sessions → ORM metadata: binds metadata
- AI service → AI provider interface: uses interface (evidence: `backend/app/services/ai_service.py`)
- Fake AI provider → AI provider interface: implements provider (evidence: `backend/app/ai/providers/fake.py`)
- AI provider router → AI provider interface: provider routing
