3-Tier Architecture

<h2 id="bkmrk-multi-component-arch">Multi-Component Architecture — SecuScan v0.28.0</h2>

<p id="bkmrk-secuscan-uses-a-dist">SecuScan uses a distributed architecture composed of 6 main application services, orchestrated on Kubernetes with multi-tenant PostgreSQL (RLS) and Redis for caching and job queues.</p>

<h3 id="bkmrk-component-diagram">Component Diagram</h3> <pre id="bkmrk-%2B-------------------"><code> +------------------------------------------------------------------+ | Kubernetes Cluster | | | | +----------+ +----------+ +----------+ +----------+ | | | Frontend | | Backend | | Worker | |Codeworker| | | | Next.js |-->| Go API |-->| Go 22 | | Go 103 | | | | 14/TS | | Chi+JWT | | tools | | functions| | | +----------+ +----+-----+ +----------+ +----------+ | | | | | +-------+-------+ | | | | | | +----v----+ +-----v----+ +----------+ | | |PostgreSQL| | Redis | | Temporal | | | | RLS/26 | | Cache/Q | | Workflow | | | | migr. | | RateLimit| | Engine | | | +---------+ +----------+ +----+-----+ | | | | | +----------+ +-------v------+ | | | Pentest | | Pentest | | | | Agent | | Worker | | | | Claude AI| | Temporal | | | +----------+ +--------------+ | +------------------------------------------------------------------+ </code></pre>

<h3 id="bkmrk-backend-api-%28go%29">Backend API (Go)</h3> <p id="bkmrk-central-service-expo">Central service exposing the multi-tenant REST API with 100+ endpoints.</p> <table id="bkmrk-aspectdetail-languag"> <thead><tr><th>Aspect</th><th>Detail</th></tr></thead> <tbody> <tr><td>Language</td><td>Go with Chi router</td></tr> <tr><td>Authentication</td><td>JWT (access + refresh tokens) + API keys (test/live)</td></tr> <tr><td>SSO</td><td>Zitadel (OIDC)</td></tr> <tr><td>Multi-tenant</td><td>PostgreSQL RLS with tenant_id in context</td></tr> <tr><td>Rate limiting</td><td>Redis-based, per pricing plan</td></tr> <tr><td>Email</td><td>Resend API (verification, password reset)</td></tr> <tr><td>Billing</td><td>Stripe (checkout, portal, subscriptions, invoices)</td></tr> <tr><td>AI</td><td>Claude AI (Anthropic) for finding analysis and reports</td></tr> <tr><td>Reporting</td><td>PDF (fpdf), CSV, Markdown (AI)</td></tr> </tbody> </table>

<h3 id="bkmrk-frontend-%28next.js-14">Frontend (Next.js 14)</h3> <table id="bkmrk-aspectdetail-framewo"> <thead><tr><th>Aspect</th><th>Detail</th></tr></thead> <tbody> <tr><td>Framework</td><td>Next.js 14, TypeScript, React</td></tr> <tr><td>Internationalization</td><td>Bilingual FR/EN via next-intl</td></tr> <tr><td>Routes</td><td>59+ routes covering all features</td></tr> <tr><td>UI</td><td>Dark/light mode, responsive design</td></tr> <tr><td>Features</td><td>Command palette (Cmd+K), global search, real-time notifications</td></tr> <tr><td>Tests</td><td>121 vitest tests</td></tr> </tbody> </table>

<h3 id="bkmrk-worker-%28go%29-%E2%80%94-22-net">Worker (Go) — 22 Network Scanning Tools</h3> <p id="bkmrk-dedicated-service-fo">Dedicated service for executing network and infrastructure scans. Communicates with the backend API via Redis job queue.</p> <p id="bkmrk-integrated-tools%3A-nm">Integrated tools: Nmap, Subfinder, Nuclei, TestSSL, DNSBL, DNS Audit, Email Security (SPF/DKIM/DMARC), Whois, HTTP Headers, WAF Detection, Robots/Sitemap, Ffuf, Gowitness, Katana, Dnstwist, Threat Intelligence (VirusTotal + AbuseIPDB), DAST, ASN/IP Cartography, DMARC/MTA-STS, Subdomain Takeover, NSE Service Audit, Certificate Transparency.</p>

<h3 id="bkmrk-codeworker-%28go%29-%E2%80%94-10">Codeworker (Go) — 103 Code Analysis Functions</h3> <p id="bkmrk-code-security-scanne">Code security scanner with 8 analysis phases:</p> <ol id="bkmrk-secret-detection-%28gi"> <li><strong>Secret detection</strong> (Gitleaks)</li> <li><strong>SAST</strong> (Gosec, Semgrep, Bandit, ESLint-Security)</li> <li><strong>Dependency analysis</strong> (npm audit, go vuln, pip audit, safety)</li> <li><strong>Code quality</strong></li> <li><strong>License compliance</strong></li> <li><strong>Container security</strong> (Trivy, Hadolint)</li> <li><strong>IaC security</strong> (tfsec, Checkov)</li> <li><strong>AI-augmented analysis</strong> (Claude AI)</li> </ol> <p id="bkmrk-new-in-v0.28.0%3A-auto"><strong>New in v0.28.0:</strong> Automatic version detection after git clone (<code>git describe --tags --always</code> + VERSION.md/package.json parsing).</p>

<h3 id="bkmrk-pentest-agent-and-wo">Pentest Agent and Worker (Go + Claude AI + Temporal)</h3> <p id="bkmrk-ai-assisted-penetrat">AI-assisted penetration testing module with Temporal orchestration for workflow management.</p> <ul id="bkmrk-phases%3A-recon%2C-enume"> <li><strong>Phases</strong>: recon, enumeration, vulnerability_assessment, exploitation, reporting</li> <li><strong>Authorization management</strong> (legal compliance, Law 25)</li> <li><strong>Finding persistence</strong> with exploitation evidence</li> </ul>

<h3 id="bkmrk-database">Database</h3> <table id="bkmrk-aspectdetail-dbmspos"> <thead><tr><th>Aspect</th><th>Detail</th></tr></thead> <tbody> <tr><td>DBMS</td><td>PostgreSQL 15</td></tr> <tr><td>Migrations</td><td>26 migrations (go-migrate, embedded via go:embed)</td></tr> <tr><td>Multi-tenant</td><td>Row Level Security (RLS) with app.current_tenant_id</td></tr> <tr><td>JSONB Types</td><td>Custom JSONMap/JSONArray types for flexibility</td></tr> <tr><td>Indexes</td><td>GIN indexes on JSONB columns</td></tr> </tbody> </table>

<h3 id="bkmrk-redis">Redis</h3> <ul id="bkmrk-caching%3A-scan-result"> <li><strong>Caching</strong>: Scan results, frequently accessed data</li> <li><strong>Job queue</strong>: Communication API to Worker/Codeworker</li> <li><strong>Rate limiting</strong>: Per pricing plan control</li> <li><strong>API tracking</strong>: API call counting per tenant</li> </ul>

<h3 id="bkmrk-docker-images-%286-ima">Docker Images (6 images)</h3> <table id="bkmrk-imagebasedescription"> <thead><tr><th>Image</th><th>Base</th><th>Description</th></tr></thead> <tbody> <tr><td>secuscan-backend</td><td>Alpine (multi-stage)</td><td>Go API, non-root (secuscan:1001), readOnlyRootFilesystem</td></tr> <tr><td>secuscan-frontend</td><td>Node Alpine</td><td>Next.js 14 SSR, non-root</td></tr> <tr><td>secuscan-worker</td><td>Alpine (multi-stage)</td><td>22 network scanning tools, non-root</td></tr> <tr><td>secuscan-codeworker</td><td>Alpine (multi-stage)</td><td>103 code analysis functions, non-root</td></tr> <tr><td>secuscan-pentest-worker</td><td>Alpine (multi-stage)</td><td>Temporal orchestration, non-root</td></tr> <tr><td>secuscan-pentest-agent</td><td>Alpine (multi-stage)</td><td>Claude AI agent, non-root</td></tr> </tbody> </table>