Plan the architecture before writing more code.

Why architecture matters

Architecture is important because it turns an idea into a system that can be understood, built, and maintained. Before writing code, we must decide where the website, backend, authentication, automation, and data should live—and how they communicate. Clear architecture reduces repeated work, avoids unnecessary complexity, and gives every repository and service a specific responsibility.

Architecture is also the first layer of security and scalability. By separating the public frontend from the private backend, validating users through the API, and keeping credentials in secure storage, we protect both users and the company. Good architecture does not mean creating a complicated system; it means choosing the simplest structure that is secure today and capable of growing tomorrow.

The architectural decision

For the current stage, three repositories are enough. This separation keeps learning material open, production code focused, and sensitive backend work private.

1. Become-SWE

This public repository contains lessons, decisions, mistakes, sanitized examples, and downloadable learning documents. It must never contain customer data, credentials, private dashboards, or confidential company information.

2. swe-tickerbell

This public repository contains the static website deployed through GitHub Pages: HTML, CSS, JavaScript, images, and public configuration. Public Auth0 identifiers may be used here, but no client secret, Brevo API key, or Google credential belongs in browser code.

3. swe-tickerbell-api

This private repository will contain the Python API, protected endpoints, authorization checks, integrations, tests, and Google Cloud deployment configuration. FastAPI on Google Cloud Run is the recommended starting point.

How the services work together

1. A visitor opens the static frontend hosted through GitHub Pages.
2. Auth0 handles registration, login, password recovery, and access tokens.
3. The frontend calls the Python API using a public or authenticated request.
4. The API validates inputs and, when required, verifies the Auth0 token and permissions.
5. The API obtains protected credentials from Google Secret Manager.
6. The API communicates with Brevo or other services and returns a limited response.

Designing for a future Brevo replacement

The backend should use an email-provider interface instead of spreading Brevo-specific code across the application. The application calls the interface, while a separate Brevo adapter implements it. A future provider can replace that adapter without rebuilding the website.

Google Cloud structure

Start with Cloud Run for the Python API, Secret Manager for credentials, Artifact Registry for container images, and Cloud Logging and Monitoring. Use separate development and production projects, each with its own service account, secrets, logs, and Auth0 configuration. Add a database only when the application genuinely needs persistent data.

Avoid Kubernetes, multiple microservices, queues, and other infrastructure until a proven requirement appears. Simplicity is part of the security model because fewer components are easier to understand, test, and maintain.

Deployment workflow

• Develop each change on a feature branch.
• Open a pull request and inspect the diff.
• Run frontend or Python tests and security checks.
• Merge approved frontend changes to deploy GitHub Pages.
• Deploy backend changes to development first.
• Require approval before production deployment.
• Use GitHub OIDC and Google Workload Identity Federation instead of long-lived service-account keys.

Essential security rules

1. Keep the learning and frontend repositories public, and the backend repository private.
2. Protect the main branch and require pull requests and tests.
3. Enable secret scanning, push protection, and dependency updates.
4. Never commit .env files, credential JSON files, tokens, passwords, or customer data.
5. Store runtime credentials only in Google Secret Manager.
6. Validate every backend input and derive identity from a validated Auth0 token.
7. Allow browser requests only from approved website origins.
8. Do not log access tokens, passwords, full sensitive requests, or email addresses unnecessarily.
9. Use separate development and production environments.
10. Rotate a credential immediately if it is accidentally exposed.

What I learned

• Planning is not a delay before development; it is development work.
• Repository boundaries should follow responsibilities, not individual tools.
• Authentication identifies users, while backend authorization controls what they may access.
• A public repository cannot protect a paid or restricted PDF.
• Secrets belong behind the backend boundary.
• The best first architecture is the simplest one that is secure and can evolve.

Architecture checklist

1. Draw the request flow before adding an integration.
2. Decide which data is public, internal, personal, or secret.
3. Assign one clear responsibility to each repository.
4. Keep privileged calls in the backend.
5. Define development and production environments.
6. Document why each major technology was selected.
7. Test the complete journey, not only the visible page.
8. Review the architecture when the product requirements change.