# cypher-aura-19/galvan-ai-website architecture

> Architecture diagram of the GitHub repository cypher-aura-19/galvan-ai-website, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cypher-aura-19/galvan-ai-website
- Repository: https://github.com/cypher-aura-19/galvan-ai-website

## Overview

1. **Overall shape**
   - This is a split-stack product: a **Next.js/React frontend** in `Frontend/` and a **Flask backend** in `backend/galvan_ai/`.
   - The frontend owns the public website, the admin dashboard UI, and a set of Next.js API routes. The backend owns persistent data, authentication, and business logic around content, newsletters, jobs, and submissions.

2. **Frontend presentation layer**
   - The frontend uses the **Next.js App Router** (`Frontend/app/...`) with TypeScript, Tailwind, and a large reusable component library under `Frontend/components/`.
   - Public pages include home, about, blogs, projects, careers, privacy policy, terms, and unsubscribe.
   - The app also includes many animation/UI primitives and shared sections like hero, services, testimonials, teams, newsletter, and navbar/footer, indicating a marketing-site style frontend with reusable content blocks.

3. **Admin UI boundary**
   - Admin pages live under `Frontend/app/admin/...` and cover dashboard, blogs, careers, jobs, projects, teams, testimonials, newsletter, applications, questionnaires, quotes, and password change.
   - `Frontend/app/admin/auth-guard.ts` plus hooks such as `useAdminSession` indicate the admin area is protected on the client side, while `middleware.ts` likely reinforces route protection.
   - The admin dashboard is a separate bounded area from the public site, not just a hidden page.

4. **Frontend API layer**
   - The frontend exposes many Next.js API routes under `Frontend/app/api/...`, grouped by domain: blogs, projects, careers, job applications, contact, questionnaires, teams, testimonials, newsletter, upload, resumes, and admin auth.
   - This creates a clear browser-facing API surface that mirrors backend capabilities and isolates the UI from direct backend implementation details.
   - `Frontend/lib/*-service.ts` files and `Frontend/lib/config.ts` suggest a service layer that centralizes backend base URLs and request logic.

5. **Backend application structure**
   - The Flask backend is organized as an application package under `backend/galvan_ai/app/`.
   - It has a dedicated auth module (`app/auth/routes.py`), an API entrypoint (`app/api.py`), and a model layer with one model per domain object: blogs, campaigns, careers, contact quotes, job applications, newsletter records, projects, questionnaires, teams, testimonials, and users.
   - This is a classic server-side domain model layout, with the backend acting as the system of record.

6. **Data and persistence**
   - The backend uses a **SQLite database** stored in `backend/galvan_ai/instance/galvan_ai.db`.
   - Database lifecycle scripts exist for creation, recreation, schema checks, and migrations (`create_db.py`, `recreate_db.py`, `check_schema.py`, migration helpers).
   - The presence of model files and migration scripts implies the backend is responsible for all durable content and operational data.

7. **Authentication flow**
   - Admin auth is handled by dedicated endpoints in both layers: frontend routes under `app/api/admin/*` and backend auth routes under `app/auth/routes.py`.
   - The admin workflow includes login, logout, dashboard access, and password change, with a seed script (`seed_admin.py`) for bootstrapping the initial administrator account.
   - The frontend admin pages depend on this auth boundary to decide whether the user can access dashboard and content-management screens.

8. **Content and operational domains**
   - The app manages several distinct business domains: editorial content (blogs, projects, testimonials, teams), hiring/careers (jobs, careers, applications, resumes), and engagement flows (contact, questionnaires, newsletter subscriptions/campaigns).
   - Some domains have specialized endpoints such as “featured” blogs/testimonials/projects and “active” careers, suggesting the frontend consumes filtered views rather than raw collections.
   - The admin dashboard likely aggregates these same domains into moderation and management screens.

9. **File and media handling**
   - File uploads are handled through `Frontend/app/api/upload` and resume retrieval through `Frontend/app/api/resumes/[fileName]`.
   - The README notes uploaded files live under `Frontend/public/uploads*` and `Frontend/uploads*`, so media assets are stored on disk rather than in the database.
   - This is an important architecture boundary: structured records live in SQLite, while binary/user-uploaded assets live in the filesystem.

10. **Email/newsletter subsystem**
   - Newsletter functionality is its own subsystem with subscribe, unsubscribe, subscribers, and campaigns endpoints in the frontend API layer.
   - `Frontend/config/smtp.js` and `Frontend/lib/email-service.ts` indicate SMTP-backed email delivery is part of the architecture.
   - The backend also includes `newsletter.py` and `campaign.py` models, so email list management and campaign data are persisted server-side.

11. **Content rendering and security**
   - Shared components like `SafeHTML` suggest the app renders rich text or CMS-authored HTML and explicitly sanitizes it before display.
   - `RichTextEditor` in the admin components confirms admins can author or edit rich content directly in the UI.
   - This combination implies a content-management workflow where backend-stored rich text is edited in admin and safely rendered in public pages.

12. **Supporting tools and legacy surface**
   - The backend includes Flask templates for `login.html` and `dashboard.html`, which suggests either a legacy server-rendered admin path or internal tooling alongside the Next.js admin UI.
   - There are repo scripts for testing job submission, sending newsletters, and debugging auth, which indicates the system is operated through a mix of UI and maintenance scripts.
   - For an architecture diagram, the main runtime boxes are still: browser → Next.js frontend/API → Flask backend → SQLite/filesystem/email.

Main entry points: [`Frontend/app`](https://github.com/cypher-aura-19/galvan-ai-website/tree/main/Frontend/app) (Next.js app), [`Frontend/app/api`](https://github.com/cypher-aura-19/galvan-ai-website/tree/main/Frontend/app/api) (API routes), [`Frontend/lib`](https://github.com/cypher-aura-19/galvan-ai-website/tree/main/Frontend/lib) (Service layer), [`backend/galvan_ai/app/auth/routes.py`](https://github.com/cypher-aura-19/galvan-ai-website/blob/main/backend/galvan_ai/app/auth/routes.py) (Auth module)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_next_app["Next.js app<br/>web frontend"]
  node_ui_components["UI components<br/>component library"]
  node_frontend_services["Service layer<br/>client services"]
  node_admin_ui["Admin area<br/>protected UI"]
  node_public_site["Public site<br/>marketing pages"]
  node_api_routes["API routes<br/>BFF/API"]
  node_auth_guard["Auth guard<br/>route protection<br/>[auth-guard.ts]"]
end

subgraph group_backend["Backend"]
  node_flask_app["Flask app<br/>backend app"]
  node_auth_module["Auth module<br/>authentication<br/>[routes.py]"]
  node_domain_models["Domain models<br/>ORM models"]
  node_backend_templates["Legacy templates<br/>server-rendered UI"]
end

subgraph group_data["Data & storage"]
  node_db_file[("SQLite DB<br/>database<br/>[galvan_ai.db]")]
  node_uploads["File uploads<br/>filesystem"]
  node_smtp["SMTP mail<br/>email delivery<br/>[smtp.js]"]
  node_newsletter_ops["Newsletter ops<br/>campaign scripts"]
  node_db_tools["DB tools<br/>maintenance scripts"]
end

node_browser(("Browser<br/>client"))

node_browser -->|"uses"| node_next_app
node_next_app -->|"renders"| node_ui_components
node_next_app -->|"serves"| node_public_site
node_next_app -->|"serves"| node_admin_ui
node_admin_ui -->|"protected by"| node_auth_guard
node_next_app -->|"calls"| node_api_routes
node_api_routes -->|"delegates"| node_frontend_services
node_frontend_services -->|"proxies to"| node_flask_app
node_api_routes -->|"admin auth"| node_auth_module
node_api_routes -->|"reads/writes"| node_db_file
node_flask_app -->|"uses"| node_domain_models
node_auth_module -->|"authenticates"| node_domain_models
node_domain_models -->|"persists"| node_db_file
node_api_routes -->|"uploads files"| node_uploads
node_frontend_services -->|"sends mail"| node_smtp
node_newsletter_ops -->|"operates"| node_smtp
node_db_tools -->|"manages"| node_db_file
node_backend_templates -.->|"supports"| node_auth_module

click node_next_app "https://github.com/cypher-aura-19/galvan-ai-website/tree/main/Frontend/app"
click node_ui_components "https://github.com/cypher-aura-19/galvan-ai-website/tree/main/Frontend/components"
click node_frontend_services "https://github.com/cypher-aura-19/galvan-ai-website/tree/main/Frontend/lib"
click node_admin_ui "https://github.com/cypher-aura-19/galvan-ai-website/tree/main/Frontend/app/admin"
click node_public_site "https://github.com/cypher-aura-19/galvan-ai-website/tree/main/Frontend/app"
click node_api_routes "https://github.com/cypher-aura-19/galvan-ai-website/tree/main/Frontend/app/api"
click node_auth_guard "https://github.com/cypher-aura-19/galvan-ai-website/blob/main/Frontend/app/admin/auth-guard.ts"
click node_flask_app "https://github.com/cypher-aura-19/galvan-ai-website/tree/main/backend/galvan_ai/app"
click node_auth_module "https://github.com/cypher-aura-19/galvan-ai-website/blob/main/backend/galvan_ai/app/auth/routes.py"
click node_domain_models "https://github.com/cypher-aura-19/galvan-ai-website/tree/main/backend/galvan_ai/app/models"
click node_backend_templates "https://github.com/cypher-aura-19/galvan-ai-website/tree/main/backend/galvan_ai/app/templates"
click node_db_file "https://github.com/cypher-aura-19/galvan-ai-website/blob/main/backend/galvan_ai/instance/galvan_ai.db"
click node_uploads "https://github.com/cypher-aura-19/galvan-ai-website/tree/main/Frontend/public"
click node_smtp "https://github.com/cypher-aura-19/galvan-ai-website/blob/main/Frontend/config/smtp.js"
click node_newsletter_ops "https://github.com/cypher-aura-19/galvan-ai-website/tree/main/Frontend/scripts"
click node_db_tools "https://github.com/cypher-aura-19/galvan-ai-website/tree/main/backend/galvan_ai"

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_next_app,node_ui_components,node_frontend_services,node_admin_ui,node_public_site,node_api_routes,node_auth_guard toneBlue
class node_flask_app,node_auth_module,node_domain_models,node_backend_templates toneAmber
class node_db_file,node_uploads,node_smtp,node_newsletter_ops,node_db_tools toneMint
class node_browser toneNeutral
```

## Components

### Frontend

Next.js app, UI components, and browser-facing API routes.

- [Next.js app](https://github.com/cypher-aura-19/galvan-ai-website/tree/main/Frontend/app): web frontend · App Router site with public pages, admin UI, and route handlers. · `Frontend/app`
- [UI components](https://github.com/cypher-aura-19/galvan-ai-website/tree/main/Frontend/components): component library · Reusable marketing, admin, and shared UI building blocks. · `Frontend/components`
- [Service layer](https://github.com/cypher-aura-19/galvan-ai-website/tree/main/Frontend/lib): client services · Frontend wrappers for auth, content, newsletters, email, and backend config. · `Frontend/lib`
- [Admin area](https://github.com/cypher-aura-19/galvan-ai-website/tree/main/Frontend/app/admin): protected UI · Protected dashboard and content-management screens for editors and operators. · `Frontend/app/admin`
- [Public site](https://github.com/cypher-aura-19/galvan-ai-website/tree/main/Frontend/app): marketing pages · Public-facing pages for home, blogs, projects, careers, policies, and unsubscribe. · `Frontend/app`
- [API routes](https://github.com/cypher-aura-19/galvan-ai-website/tree/main/Frontend/app/api): BFF/API · Browser-facing Next.js endpoints for content, admin auth, uploads, and newsletters. · `Frontend/app/api`
- [Auth guard](https://github.com/cypher-aura-19/galvan-ai-website/blob/main/Frontend/app/admin/auth-guard.ts): route protection · Client-side session checks and middleware-based admin access control. · `Frontend/app/admin/auth-guard.ts`

### Backend

Flask application, domain models, and auth/business logic.

- [Flask app](https://github.com/cypher-aura-19/galvan-ai-website/tree/main/backend/galvan_ai/app): backend app · Server application entrypoint and API surface for domain logic. · `backend/galvan_ai/app`
- [Auth module](https://github.com/cypher-aura-19/galvan-ai-website/blob/main/backend/galvan_ai/app/auth/routes.py): authentication · Backend login, logout, and password-change routes for admin access. · `backend/galvan_ai/app/auth/routes.py`
- [Domain models](https://github.com/cypher-aura-19/galvan-ai-website/tree/main/backend/galvan_ai/app/models): ORM models · Server-side models for blogs, projects, careers, applications, newsletters, teams, testimonials, and users. · `backend/galvan_ai/app/models`
- [Legacy templates](https://github.com/cypher-aura-19/galvan-ai-website/tree/main/backend/galvan_ai/app/templates): server-rendered UI · Flask templates for login and dashboard, likely a legacy or internal admin path. · `backend/galvan_ai/app/templates`

### Data & storage

Persistent database, uploads, and email delivery surfaces.

- [SQLite DB](https://github.com/cypher-aura-19/galvan-ai-website/blob/main/backend/galvan_ai/instance/galvan_ai.db): database · Persistent application data store. · `backend/galvan_ai/instance/galvan_ai.db`
- [File uploads](https://github.com/cypher-aura-19/galvan-ai-website/tree/main/Frontend/public): filesystem · Stored uploaded assets and resumes on disk. · `Frontend/public`
- [SMTP mail](https://github.com/cypher-aura-19/galvan-ai-website/blob/main/Frontend/config/smtp.js): email delivery · Outbound email delivery for newsletter and related notifications. · `Frontend/config/smtp.js`
- [Newsletter ops](https://github.com/cypher-aura-19/galvan-ai-website/tree/main/Frontend/scripts): campaign scripts · Scripts for subscriber sends and delivery operations. · `Frontend/scripts`
- [DB tools](https://github.com/cypher-aura-19/galvan-ai-website/tree/main/backend/galvan_ai): maintenance scripts · Database creation, recreation, migration, and schema-check utilities. · `backend/galvan_ai`

### Other components

- **Browser**: client · Users and admins interact with the public site and admin dashboard here.

## Connections

- Browser → Next.js app: uses · Users load pages and interact with the app.
- Next.js app → UI components: renders · Pages assemble reusable UI sections and primitives.
- Next.js app → Public site: serves · Public routes render the marketing site and content pages.
- Next.js app → Admin area: serves · Admin routes render dashboard and management screens.
- Admin area → Auth guard: protected by · Admin access is gated on the client and via middleware.
- Next.js app → API routes: calls · Pages use Next.js route handlers for data access.
- API routes → Service layer: delegates · Route handlers and client wrappers centralize backend requests.
- Service layer → Flask app: proxies to · Frontend services forward business operations to the Flask backend.
- API routes → Auth module: admin auth · Login, logout, and password change are exposed through API routes.
- API routes → SQLite DB: reads/writes · Structured content and operational data ultimately persist server-side.
- Flask app → Domain models: uses · The backend organizes each business domain as a model.
- Auth module → Domain models: authenticates · Auth operations depend on the user model and admin records.
- Domain models → SQLite DB: persists · Models map to the SQLite system of record.
- API routes → File uploads: uploads files · Media and resume files are handled on disk rather than in the database.
- Service layer → SMTP mail: sends mail · Newsletter and email flows rely on SMTP-backed delivery.
- Newsletter ops → SMTP mail: operates · Scripts support sending newsletters through the mail subsystem.
- DB tools → SQLite DB: manages · Scripts create, migrate, and verify the SQLite database.
- Legacy templates → Auth module: supports · Legacy server-rendered admin pages share the backend auth boundary.