How cypher-aura-19/galvan-ai-website works
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: app Next.js app · api API routes · lib Service layer · routes.py Auth module
Components 17
Frontend
Next.js app, UI components, and browser-facing API routes.
- Next.js app · App Router site with public pages, admin UI, and route handlers.
Frontend/app - UI components · Reusable marketing, admin, and shared UI building blocks.
Frontend/components - Service layer · Frontend wrappers for auth, content, newsletters, email, and backend config.
Frontend/lib - Admin area · Protected dashboard and content-management screens for editors and operators.
Frontend/app/admin - Public site · Public-facing pages for home, blogs, projects, careers, policies, and unsubscribe.
Frontend/app - API routes · Browser-facing Next.js endpoints for content, admin auth, uploads, and newsletters.
Frontend/app/api - Auth guard · 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 · Server application entrypoint and API surface for domain logic.
backend/galvan_ai/app - Auth module · Backend login, logout, and password-change routes for admin access.
backend/galvan_ai/app/auth/routes.py - Domain models · Server-side models for blogs, projects, careers, applications, newsletters, teams, testimonials, and users.
backend/galvan_ai/app/models - Legacy templates · 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 · Persistent application data store.
backend/galvan_ai/instance/galvan_ai.db - File uploads · Stored uploaded assets and resumes on disk.
Frontend/public - SMTP mail · Outbound email delivery for newsletter and related notifications.
Frontend/config/smtp.js - Newsletter ops · Scripts for subscriber sends and delivery operations.
Frontend/scripts - DB tools · Database creation, recreation, migration, and schema-check utilities.
backend/galvan_ai
Other components
- Browser · Users and admins interact with the public site and admin dashboard here.
Connections 18
- 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.