# aakash-kr-7/google_calender_clone architecture

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

- Interactive diagram: https://gitdiagram.com/aakash-kr-7/google_calender_clone
- Repository: https://github.com/aakash-kr-7/google_calender_clone

## Overview

1. **Overall shape**
   - This is a split full-stack calendar app: a React single-page frontend in `frontend/` and a FastAPI backend in `backend/`, with a local SQLite database as the persistence layer.
   - The main user flow is: browser UI → API requests → backend validation/business logic → SQLite → response back to the UI.

2. **Frontend boundary**
   - The frontend is a Vite/React app organized around calendar views and event interactions rather than a generic page hierarchy.
   - `src/App.jsx` and `src/main.jsx` boot the app, while `components/layout/` provides the shell, navigation, palette, sidebar, and settings surfaces that frame the calendar experience.

3. **Calendar rendering subsystem**
   - The calendar UI is split into `components/views/DayView.jsx`, `WeekView.jsx`, and `MonthView.jsx`, backed by lower-level calendar primitives in `components/calendar/`.
   - `TimeGrid`, `AllDayRow`, and `MiniCalendar` suggest the page is composed from reusable layout blocks that are reused across views rather than fully separate screens.

4. **Event interaction subsystem**
   - Event creation and editing are centered in `components/events/` through modal, popover, hover-preview, form, and block components.
   - This indicates the UI supports multiple event entry points: clicking a time slot, editing an existing event, hovering for details, and dragging/resizing blocks directly on the calendar.

5. **Client-side state and data access**
   - The app uses small client-side stores in `src/store/` (`calendarStore.js`, `eventStore.js`, `settingsStore.js`) plus hooks like `useEvents`, `useDragDrop`, and `useResize`.
   - `src/api/client.js` is the network boundary: the UI state reads from and writes to the backend through this client, rather than talking to the API directly from components.

6. **Frontend business logic**
   - Calendar-specific calculations are kept in `src/utils/`, including date handling, event layout, slot finding, and timezone conversion.
   - This separation matters because the frontend is not just rendering server data; it also computes event positioning, conflict-adjacent UX, and local-time display behavior before painting the calendar.

7. **Authentication boundary**
   - The backend exposes an auth router in `backend/app/routers/auth.py`, and the frontend has dedicated `LoginPage.jsx` and `RegisterPage.jsx`.
   - The README indicates JWT-based auth and Google OAuth support, so authentication is a first-class boundary between anonymous entry, signed-in state, and protected event operations.

8. **Backend API structure**
   - FastAPI route handlers are divided into `routers/auth.py` and `routers/events.py`, which keeps identity concerns separate from calendar CRUD and scheduling concerns.
   - `backend/app/main.py` is the application entrypoint, while `backend/app/__init__.py` and `backend/app/database.py` anchor startup and persistence setup.

9. **Backend domain model and service layer**
   - Domain objects live in `backend/app/models/` with at least `user.py` and `event.py`, and request/response contracts are defined separately in `backend/app/schemas/`.
   - Event-specific business logic is pushed into `backend/app/services/event_service.py`, which is the main place where the app likely handles overlap detection, recurrence-aware behavior, and mutation rules before data hits the database.

10. **Persistence and migration path**
   - SQLite is the storage backend, with database initialization/migration handled by `backend/migrate.py`.
   - The README and file layout suggest a simple single-file database deployment model, which fits the repo’s local/dev-friendly setup and the Render deployment described in the docs.

11. **Time handling boundary**
   - `backend/app/utils/timezone.py` and `frontend/src/utils/timezone.js` show that timezone conversion exists on both sides of the stack.
   - This is important architecturally because calendar correctness depends on keeping stored timestamps, API payloads, and rendered local times aligned across the client/server boundary.

12. **Deployment split**
   - The repo is designed for separate deployment of frontend and backend: the frontend on Vercel and the backend as a Python service on Render.
   - That means the browser talks to the API over the network, and the frontend is not server-rendered by the backend.

13. **Notable cross-cutting concerns**
   - The codebase clearly treats event scheduling as a core domain concern: dragging, resizing, popovers, command palette actions, and modal editing all converge on the same event data model.
   - The architecture therefore revolves around one central resource type, `event`, with `user` acting as the access boundary and ownership boundary.

14. **Good diagram anchors**
   - For an architecture diagram, the most important boxes are: React UI shell, calendar view layer, event interaction layer, client state/API client, FastAPI routers, event service, auth service, and SQLite tables for users/events.
   - The key arrows are: user actions into React, React into API client, API client into auth/events routers, routers into service logic, service into SQLite, and responses back to the stores/UI.

Main entry points: [`frontend/src/components/layout/Layout.jsx`](https://github.com/aakash-kr-7/google_calender_clone/blob/main/frontend/src/components/layout/Layout.jsx) (Layout), [`frontend/src/components/views/DayView.jsx`](https://github.com/aakash-kr-7/google_calender_clone/blob/main/frontend/src/components/views/DayView.jsx) (Calendar views), [`backend/app/services/event_service.py`](https://github.com/aakash-kr-7/google_calender_clone/blob/main/backend/app/services/event_service.py) (Event service), [`frontend/src/components/events/EventModal.jsx`](https://github.com/aakash-kr-7/google_calender_clone/blob/main/frontend/src/components/events/EventModal.jsx) (Event UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App shell<br/>React boot<br/>[App.jsx]"]
  node_frontend_layout["Layout<br/>UI shell<br/>[Layout.jsx]"]
  node_frontend_views["Calendar views<br/>view layer<br/>[DayView.jsx]"]
  node_frontend_calendar_primitives["Calendar blocks<br/>calendar primitives<br/>[TimeGrid.jsx]"]
  node_frontend_event_ui["Event UI<br/>interaction layer<br/>[EventModal.jsx]"]
  node_frontend_pages["Auth pages<br/>entry pages<br/>[LoginPage.jsx]"]
  node_frontend_state["Client state<br/>stores<br/>[eventStore.js]"]
  node_frontend_api["API client<br/>network boundary<br/>[client.js]"]
  node_frontend_utils["Date logic<br/>client utils<br/>[eventLayout.js]"]
end

subgraph group_backend["Backend"]
  node_backend_main["App entry<br/>FastAPI boot<br/>[main.py]"]
  node_backend_routers_auth["Auth router<br/>API routes<br/>[auth.py]"]
  node_backend_routers_events["Events router<br/>API routes<br/>[events.py]"]
  node_backend_service["Event service<br/>domain logic<br/>[event_service.py]"]
  node_backend_models["Domain models<br/>ORM models<br/>[event.py]"]
  node_backend_schemas["API schemas<br/>contracts<br/>[event.py]"]
  node_backend_db[("SQLite DB<br/>persistence<br/>[database.py]")]
  node_backend_migrate["Migration<br/>db setup<br/>[migrate.py]"]
  node_backend_timezone["Timezone utils<br/>time handling<br/>[timezone.py]"]
end

node_frontend_app -->|"composes"| node_frontend_layout
node_frontend_layout -->|"renders"| node_frontend_views
node_frontend_layout -->|"opens"| node_frontend_event_ui
node_frontend_layout -->|"switches"| node_frontend_pages
node_frontend_views -->|"uses"| node_frontend_calendar_primitives
node_frontend_views -->|"shows"| node_frontend_event_ui
node_frontend_event_ui -->|"updates"| node_frontend_state
node_frontend_state -->|"syncs"| node_frontend_api
node_frontend_utils -->|"supports"| node_frontend_views
node_frontend_utils -->|"supports"| node_frontend_event_ui
node_frontend_api -->|"calls"| node_backend_routers_auth
node_frontend_api -->|"calls"| node_backend_routers_events
node_backend_main -->|"mounts"| node_backend_routers_auth
node_backend_main -->|"mounts"| node_backend_routers_events
node_backend_routers_auth -->|"validates"| node_backend_schemas
node_backend_routers_events -->|"delegates"| node_backend_service
node_backend_service -->|"persists"| node_backend_models
node_backend_service -->|"stores"| node_backend_db
node_backend_models -->|"maps to"| node_backend_db
node_backend_migrate -->|"initializes"| node_backend_db
node_backend_timezone -->|"supports"| node_backend_service
node_frontend_utils -.->|"aligns with"| node_backend_timezone

click node_frontend_app "https://github.com/aakash-kr-7/google_calender_clone/blob/main/frontend/src/App.jsx"
click node_frontend_layout "https://github.com/aakash-kr-7/google_calender_clone/blob/main/frontend/src/components/layout/Layout.jsx"
click node_frontend_views "https://github.com/aakash-kr-7/google_calender_clone/blob/main/frontend/src/components/views/DayView.jsx"
click node_frontend_calendar_primitives "https://github.com/aakash-kr-7/google_calender_clone/blob/main/frontend/src/components/calendar/TimeGrid.jsx"
click node_frontend_event_ui "https://github.com/aakash-kr-7/google_calender_clone/blob/main/frontend/src/components/events/EventModal.jsx"
click node_frontend_pages "https://github.com/aakash-kr-7/google_calender_clone/blob/main/frontend/src/pages/LoginPage.jsx"
click node_frontend_state "https://github.com/aakash-kr-7/google_calender_clone/blob/main/frontend/src/store/eventStore.js"
click node_frontend_api "https://github.com/aakash-kr-7/google_calender_clone/blob/main/frontend/src/api/client.js"
click node_frontend_utils "https://github.com/aakash-kr-7/google_calender_clone/blob/main/frontend/src/utils/eventLayout.js"
click node_backend_main "https://github.com/aakash-kr-7/google_calender_clone/blob/main/backend/app/main.py"
click node_backend_routers_auth "https://github.com/aakash-kr-7/google_calender_clone/blob/main/backend/app/routers/auth.py"
click node_backend_routers_events "https://github.com/aakash-kr-7/google_calender_clone/blob/main/backend/app/routers/events.py"
click node_backend_service "https://github.com/aakash-kr-7/google_calender_clone/blob/main/backend/app/services/event_service.py"
click node_backend_models "https://github.com/aakash-kr-7/google_calender_clone/blob/main/backend/app/models/event.py"
click node_backend_schemas "https://github.com/aakash-kr-7/google_calender_clone/blob/main/backend/app/schemas/event.py"
click node_backend_db "https://github.com/aakash-kr-7/google_calender_clone/blob/main/backend/app/database.py"
click node_backend_migrate "https://github.com/aakash-kr-7/google_calender_clone/blob/main/backend/migrate.py"
click node_backend_timezone "https://github.com/aakash-kr-7/google_calender_clone/blob/main/backend/app/utils/timezone.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_app,node_frontend_layout,node_frontend_views,node_frontend_calendar_primitives,node_frontend_event_ui,node_frontend_pages,node_frontend_state,node_frontend_api,node_frontend_utils toneBlue
class node_backend_main,node_backend_routers_auth,node_backend_routers_events,node_backend_service,node_backend_models,node_backend_schemas,node_backend_db,node_backend_migrate,node_backend_timezone toneAmber
```

## Components

### Frontend

React/Vite single-page calendar UI and client-side state

- [App shell](https://github.com/aakash-kr-7/google_calender_clone/blob/main/frontend/src/App.jsx): React boot · Entry points and top-level app composition · `frontend/src/App.jsx`
- [Layout](https://github.com/aakash-kr-7/google_calender_clone/blob/main/frontend/src/components/layout/Layout.jsx): UI shell · Global shell, header, sidebar, palette, and settings surfaces · `frontend/src/components/layout/Layout.jsx`
- [Calendar views](https://github.com/aakash-kr-7/google_calender_clone/blob/main/frontend/src/components/views/DayView.jsx): view layer · Day, week, and month calendar screens · `frontend/src/components/views/DayView.jsx`
- [Calendar blocks](https://github.com/aakash-kr-7/google_calender_clone/blob/main/frontend/src/components/calendar/TimeGrid.jsx): calendar primitives · Reusable grid and mini-calendar building blocks · `frontend/src/components/calendar/TimeGrid.jsx`
- [Event UI](https://github.com/aakash-kr-7/google_calender_clone/blob/main/frontend/src/components/events/EventModal.jsx): interaction layer · Modal, popover, hover preview, forms, and draggable event blocks · `frontend/src/components/events/EventModal.jsx`
- [Auth pages](https://github.com/aakash-kr-7/google_calender_clone/blob/main/frontend/src/pages/LoginPage.jsx): entry pages · Login and registration screens · `frontend/src/pages/LoginPage.jsx`
- [Client state](https://github.com/aakash-kr-7/google_calender_clone/blob/main/frontend/src/store/eventStore.js): stores · Calendar, event, and settings stores plus event hooks · `frontend/src/store/eventStore.js`
- [API client](https://github.com/aakash-kr-7/google_calender_clone/blob/main/frontend/src/api/client.js): network boundary · Single client used by the UI to call backend endpoints · `frontend/src/api/client.js`
- [Date logic](https://github.com/aakash-kr-7/google_calender_clone/blob/main/frontend/src/utils/eventLayout.js): client utils · Event layout, slot finding, date, and timezone helpers · `frontend/src/utils/eventLayout.js`

### Backend

FastAPI API, domain logic, and SQLite persistence

- [App entry](https://github.com/aakash-kr-7/google_calender_clone/blob/main/backend/app/main.py): FastAPI boot · Backend startup and application wiring · `backend/app/main.py`
- [Auth router](https://github.com/aakash-kr-7/google_calender_clone/blob/main/backend/app/routers/auth.py): API routes · Authentication and identity endpoints · `backend/app/routers/auth.py`
- [Events router](https://github.com/aakash-kr-7/google_calender_clone/blob/main/backend/app/routers/events.py): API routes · Calendar CRUD and scheduling endpoints · `backend/app/routers/events.py`
- [Event service](https://github.com/aakash-kr-7/google_calender_clone/blob/main/backend/app/services/event_service.py): domain logic · Business rules for event validation and mutation · `backend/app/services/event_service.py`
- [Domain models](https://github.com/aakash-kr-7/google_calender_clone/blob/main/backend/app/models/event.py): ORM models · User and event persistence objects · `backend/app/models/event.py`
- [API schemas](https://github.com/aakash-kr-7/google_calender_clone/blob/main/backend/app/schemas/event.py): contracts · Request and response shapes for users and events · `backend/app/schemas/event.py`
- [SQLite DB](https://github.com/aakash-kr-7/google_calender_clone/blob/main/backend/app/database.py): persistence · Local database connection and storage layer · `backend/app/database.py`
- [Migration](https://github.com/aakash-kr-7/google_calender_clone/blob/main/backend/migrate.py): db setup · Database initialization and migration script · `backend/migrate.py`
- [Timezone utils](https://github.com/aakash-kr-7/google_calender_clone/blob/main/backend/app/utils/timezone.py): time handling · Server-side timezone conversion helpers · `backend/app/utils/timezone.py`

## Connections

- App shell → Layout: composes · App bootstraps the main shell
- Layout → Calendar views: renders · Shell hosts the calendar view layer
- Layout → Event UI: opens · Shell surfaces event editing and interaction controls
- Layout → Auth pages: switches · Shell also hosts auth entry screens
- Calendar views → Calendar blocks: uses · Day, week, and month views reuse shared calendar blocks
- Calendar views → Event UI: shows · Views place event blocks and interaction affordances
- Event UI → Client state: updates · Event interactions flow through client stores and hooks
- Client state → API client: syncs · Stores read and write via the API client
- Date logic → Calendar views: supports · Date and layout helpers drive calendar rendering
- Date logic → Event UI: supports · Layout, slot, and timezone logic inform event interaction
- API client → Auth router: calls · Client sends auth requests to the backend
- API client → Events router: calls · Client sends calendar requests to the backend
- App entry → Auth router: mounts · Application wires in the auth router
- App entry → Events router: mounts · Application wires in the events router
- Auth router → API schemas: validates · Auth routes use typed request and response contracts
- Events router → Event service: delegates · Event routes hand off business rules to the service layer
- Event service → Domain models: persists · Service reads and writes domain models
- Event service → SQLite DB: stores · Business logic ultimately commits to SQLite
- Domain models → SQLite DB: maps to · ORM models correspond to database tables
- Migration → SQLite DB: initializes · Migration script prepares the SQLite database
- Timezone utils → Event service: supports · Server-side scheduling logic depends on timezone conversion
- Date logic → Timezone utils: aligns with · Client and server both handle timezone normalization